class Riffer::Params::Param

A single parameter definition, handling type validation and JSON Schema generation.

Constants

JSON_TYPE_MAPPINGS: Maps JSON Schema type strings back to Ruby types (inverse of TYPE_MAPPINGS), collapsing the three boolean spellings onto Riffer::Params::Boolean.
PRIMITIVE_TYPES: Primitive types allowed for the of: keyword on Array params
TYPE_MAPPINGS: Maps Ruby types to JSON Schema type strings

Attributes

default [R]

The default value, if any.

description [R]

The parameter description, if any.

enum [R]

Allowed values, if constrained.

item_type [R]

Element type for a typed array (of:).

name [R]

The parameter name.

nested_params [R]

Nested Params for object / array-of-object types.

required [R]

Whether the parameter is required.

type [R]

The Ruby type.

Public Class Methods

from_json_schema (name, schema, required:)

Source

# File lib/riffer/params/param.rb, line 61
def self.from_json_schema(name, schema, required:)
  ruby_type = json_type_to_ruby(schema[:type])
  item_type, nested = resolve_nesting(ruby_type, schema)

  new(
    name: name,
    type: ruby_type,
    required: required,
    description: schema[:description],
    enum: schema[:enum],
    default: schema[:default],
    item_type: item_type,
    nested_params: nested
  )
end

Reconstructs a Param from a single JSON Schema property. Raises Riffer::ArgumentError on a type outside the Params-expressible subset.

new (name:, type:, required:, description: nil, enum: nil, default: nil, item_type: nil, nested_params: nil)

Source

# File lib/riffer/params/param.rb, line 104
def initialize(name:, type:, required:, description: nil, enum: nil, default: nil, item_type: nil, nested_params: nil)
  @name = name.to_sym
  @type = type
  @required = required
  @description = description
  @enum = enum
  @default = default
  @item_type = item_type
  @nested_params = nested_params
end

Public Instance Methods

to_json_schema (strict: false)

Source

# File lib/riffer/params/param.rb, line 144
def to_json_schema(strict: false)
  nullable = strict && !required

  if nullable && enum
    schema = {anyOf: [{type: type_name, enum: enum}, {type: "null"}]} #: Hash[Symbol, untyped]
    schema[:description] = description if description
    return schema
  end

  type = type_name
  type = [type, "null"] if nullable

  schema = {type: type} #: Hash[Symbol, untyped]
  schema[:description] = description if description
  schema[:enum] = enum if enum
  # Strict providers reject the +default+ keyword; emit it only in
  # non-strict mode, where it makes the schema a lossless round-trip
  # source for +from_json_schema+.
  schema[:default] = default unless strict || default.nil?

  if self.type == Array && nested_params
    schema[:items] = nested_params.to_json_schema(strict: strict)
  elsif self.type == Array && item_type
    schema[:items] = {type: TYPE_MAPPINGS[item_type]}
  elsif self.type == Hash && nested_params
    schema.merge!(nested_params.to_json_schema(strict: strict))
  end

  schema
end

Converts this parameter to JSON Schema format. When strict, optional params are made nullable (["type", "null"]) so strict providers distinguish absent from present; optional params with an enum use anyOf instead, since providers like Anthropic reject {"type": ["string", "null"], "enum": [...]}.

type_name ()

Source

# File lib/riffer/params/param.rb, line 133
def type_name
  TYPE_MAPPINGS[type] || type.to_s.downcase
end

Returns the JSON Schema type name for this parameter.

valid_type? (value)

Source

# File lib/riffer/params/param.rb, line 119
def valid_type?(value)
  return true if value.nil? && !required

  if type == Riffer::Params::Boolean || type == TrueClass || type == FalseClass
    value == true || value == false
  else
    value.is_a?(type)
  end
end

Validates that a value matches the expected type.