Class: OpenRouter::Schema

Inherits:
Object
  • Object
show all
Defined in:
lib/open_router/schema.rb

Defined Under Namespace

Classes: ItemsBuilder, SchemaBuilder

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, schema_definition = {}, strict: true) ⇒ Schema

Returns a new instance of Schema.

Raises:

  • (ArgumentError) 


15
16
17
18
19
20
21
22
 
# File 'lib/open_router/schema.rb', line 15

def initialize(name, schema_definition = {}, strict: true)
  @name = name
  @strict = strict
  raise ArgumentError, "Schema definition must be a hash" unless schema_definition.is_a?(Hash)

  @schema = schema_definition
  validate_schema!
end

Instance Attribute Details

#name ⇒ Object (readonly)

Returns the value of attribute name.



13
14
15
 
# File 'lib/open_router/schema.rb', line 13

def name
  @name
end

#schema ⇒ Object (readonly)

Returns the value of attribute schema.



13
14
15
 
# File 'lib/open_router/schema.rb', line 13

def schema
  @schema
end

#strict ⇒ Object (readonly)

Returns the value of attribute strict.



13
14
15
 
# File 'lib/open_router/schema.rb', line 13

def strict
  @strict
end

Class Method Details

.define(name, strict: true, &block) ⇒ Object

Class method for defining schemas with a DSL



25
26
27
28
29
 
# File 'lib/open_router/schema.rb', line 25

def self.define(name, strict: true, &block)
  builder = SchemaBuilder.new
  builder.instance_eval(&block) if block_given?
  new(name, builder.to_h, strict:)
end

Instance Method Details

#get_format_instructions(forced: false) ⇒ Object

Generate format instructions for model prompting



80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/open_router/schema.rb', line 80

def get_format_instructions(forced: false)
  schema_json = to_h.to_json

  if forced
    "      You must format your output as a JSON value that conforms exactly to the following JSON Schema specification:\n\n      \#{schema_json}\n\n      CRITICAL: Your entire response must be valid JSON that matches this schema. Do not include any text before or after the JSON. Return ONLY the JSON value itself - no other text, explanations, or formatting.\n\n      example format:\n      ```json\n      {\"field1\": \"value1\", \"field2\": \"value2\"}\n      ```\n\n      Important guidelines:\n      - Ensure all required fields match the schema exactly\n      - Use proper JSON formatting (no trailing commas)\n      - All string values must be properly quoted\n    INSTRUCTIONS\n  else\n    <<~INSTRUCTIONS\n      Please format your output as a JSON value that conforms to the following JSON Schema specification:\n\n      \#{schema_json}\n\n      Your response should be valid JSON that matches this schema structure exactly.\n\n      example format:\n      ```json\n      {\"field1\": \"value1\", \"field2\": \"value2\"}\n      ```\n\n      Important guidelines:\n      - Ensure all required fields match the schema\n      - Use proper JSON formatting (no trailing commas)\n      - Return ONLY the JSON - no other text or explanations\n    INSTRUCTIONS\n  end\nend\n"

#pure_schema ⇒ Object

Get the pure JSON Schema (respects required flags) for testing/validation



52
53
54
 
# File 'lib/open_router/schema.rb', line 52

def pure_schema
  @schema
end

#to_h ⇒ Object

Convert to the format expected by OpenRouter API



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/open_router/schema.rb', line 32

def to_h
  # Apply OpenRouter-specific transformations
  openrouter_schema = @schema.dup

  # OpenRouter/Azure requires ALL properties to be in the required array
  # even if they are logically optional. This is a deviation from JSON Schema spec
  # but necessary for compatibility.
  if openrouter_schema[:properties]&.any?
    all_properties = openrouter_schema[:properties].keys.map(&:to_s)
    openrouter_schema[:required] = all_properties
  end

  {
    name: @name,
    strict: @strict,
    schema: openrouter_schema
  }
end

#to_json(*args) ⇒ Object 



56
57
58
 
# File 'lib/open_router/schema.rb', line 56

def to_json(*args)
  to_h.to_json(*args)
end

#validate(data) ⇒ Object

Validate data against this schema



66
67
68
69
70
 
# File 'lib/open_router/schema.rb', line 66

def validate(data)
  return true unless defined?(JSON::Validator)

  JSON::Validator.validate(@schema, data)
end

#validation_available? ⇒ Boolean

Check if JSON schema validation is available

Returns:

  • (Boolean) 


61
62
63
 
# File 'lib/open_router/schema.rb', line 61

def validation_available?
  !!defined?(JSON::Validator)
end

#validation_errors(data) ⇒ Object

Get validation errors for data



73
74
75
76
77
 
# File 'lib/open_router/schema.rb', line 73

def validation_errors(data)
  return [] unless defined?(JSON::Validator)

  JSON::Validator.fully_validate(@schema, data)
end