Class: EasyTalk::Property

Inherits:
Object
  • Object
show all
Extended by:
T::Sig
Defined in:
lib/easy_talk/property.rb

Overview

Property class for building a JSON schema property.

This class handles the conversion from Ruby types to JSON Schema property definitions, and provides support for common constraints like minimum/maximum values, string patterns, and custom validators.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, type = nil, constraints = {}) ⇒ Property

Returns a new instance of Property.

Raises:

  • (ArgumentError) 


66
67
68
69
70
71
72
73
74
75
 
# File 'lib/easy_talk/property.rb', line 66

def initialize(name, type = nil, constraints = {})
  @name = name
  @type = type
  @constraints = constraints
  if type.nil? || (type.respond_to?(:empty?) && type.is_a?(String) && type.strip.empty?)
    raise ArgumentError,
          'property type is missing'
  end
  raise ArgumentError, 'property type is not supported' if type.is_a?(Array) && type.empty?
end

Instance Attribute Details

#constraints ⇒ Hash<Symbol, Object> (readonly)

Returns Additional constraints applied to the property.

Returns:

  • (Hash<Symbol, Object>) —

    Additional constraints applied to the property



46
47
48
 
# File 'lib/easy_talk/property.rb', line 46

def constraints
  @constraints
end

#name ⇒ Symbol (readonly)

Returns The name of the property.

Returns:

  • (Symbol) —

    The name of the property



40
41
42
 
# File 'lib/easy_talk/property.rb', line 40

def name
  @name
end

#type ⇒ Object (readonly)

Returns The type definition of the property.

Returns:

  • (Object) —

    The type definition of the property



43
44
45
 
# File 'lib/easy_talk/property.rb', line 43

def type
  @type
end

Instance Method Details

#as_json(*_args) ⇒ Hash

Converts the property definition to a JSON-compatible format.

This method enables seamless integration with Ruby's JSON library.

Parameters:

  • _args (Array) —

    Optional arguments passed to #as_json (ignored)

Returns:

  • (Hash) —

    The JSON-compatible representation of the property schema

See Also:



131
132
133
 
# File 'lib/easy_talk/property.rb', line 131

def as_json(*_args)
  build.as_json
end

#build ⇒ Hash

Builds the property schema based on its type and constraints.

This method handles different types of properties:

  • Nilable types (can be null)
  • Types with dedicated builders
  • Types that implement their own schema method (EasyTalk models)
  • Default fallback to 'object' type

When use_refs is enabled (globally or per-property), EasyTalk models are referenced via $ref instead of being inlined.

Examples:

Simple string property

property = Property.new(:name, 'String')
property.build  # => {"type"=>"string"}

Complex nested schema (inlined)

address = Address.new  # A class with a .schema method
property = Property.new(:shipping_address, address, description: "Shipping address")
property.build  # => Address schema merged with the description constraint

Nested schema with $ref

property = Property.new(:shipping_address, Address, ref: true)
property.build  # => {"$ref"=>"#/$defs/Address", ...constraints}

Returns:

  • (Hash) —

    The complete JSON Schema property definition



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/easy_talk/property.rb', line 102

def build
  if nilable_type?
    build_nilable_schema
  elsif RefHelper.should_use_ref?(type, constraints)
    RefHelper.build_ref_schema(type, constraints)
  elsif (resolved = find_builder_for_type)
    builder_class, is_collection = resolved
    args = is_collection ? [name, type, constraints] : [name, constraints]
    builder_class.new(*args).build
  elsif type.respond_to?(:schema)
    # merge the top-level constraints from *this* property
    # e.g. :title, :description, :default, etc
    type.schema.merge!(constraints)
  else
    raise UnknownTypeError,
          "Unknown type '#{type.inspect}' for property '#{name}'. " \
          'Register a custom builder with EasyTalk.register_type or use a supported type.'
  end
end