Class: Ask::Schema

Inherits:
Object
  • Object
show all
Extended by:
DSL
Includes:
JsonOutput
Defined in:
lib/ask-schema.rb,
lib/ask/schema/dsl.rb,
lib/ask/schema/errors.rb,
lib/ask/schema/helpers.rb,
lib/ask/schema/version.rb,
lib/ask/schema/validator.rb,
lib/ask/schema/json_output.rb,
lib/ask/schema/dsl/utilities.rb,
lib/ask/schema/dsl/conditionals.rb,
lib/ask/schema/dsl/complex_types.rb,
lib/ask/schema/dsl/primitive_types.rb,
lib/ask/schema/dsl/schema_builders.rb

Overview

Build standards-compliant JSON Schema documents using a compact Ruby DSL.

Supports both block-based and class-based usage patterns, with full support for JSON Schema Draft 07/2020-12 features including composition, conditionals, definitions, and validation.

Examples:

Block-based DSL

schema = Ask::Schema.create do
  string :name, description: "Full name"
  integer :age, minimum: 0
end
schema.new("user").to_json_schema

Class-based DSL

class Product < Ask::Schema
  string :name, description: "Product name"
  number :price
end
Product.new("product").to_json_schema

Defined Under Namespace

Modules: DSL, Helpers, JsonOutput Classes: Error, InvalidArrayTypeError, InvalidObjectTypeError, InvalidSchemaError, InvalidSchemaTypeError, LimitExceededError, ValidationError, Validator

Constant Summary collapse

PRIMITIVE_TYPES =

Primitive JSON Schema types available in the DSL.

%i[string number integer boolean null].freeze
VERSION = 
"0.1.0"

Class Method Summary collapse

Instance Method Summary collapse

Methods included from DSL::Utilities

#define, #reference

Methods included from DSL::Conditionals

#conditions, #dependencies, #dependent, #given

Methods included from DSL::ComplexTypes

#any_of, #array, #object, #one_of, #optional

Methods included from DSL::PrimitiveTypes

#boolean, #integer, #null, #number, #string

Methods included from DSL::SchemaBuilders

#any_of_schema, #array_schema, #boolean_schema, #integer_schema, #null_schema, #number_schema, #object_schema, #one_of_schema, #string_schema

Methods included from JsonOutput

#to_json, #to_json_schema

Constructor Details

#initialize(name = nil, description: nil) ⇒ Schema

Create a new schema instance.

Parameters:

  • name (String, nil) (defaults to: nil) —

    Instance name (overrides class name in JSON output)

  • description (String, nil) (defaults to: nil) —

    Instance description (overrides class description)



142
143
144
145
 
# File 'lib/ask-schema.rb', line 142

def initialize(name = nil, description: nil)
  @name = name || self.class.name || "Schema"
  @description = description
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method_name) ⇒ Object

Delegate DSL methods (string, number, integer, etc.) to the class level.



163
164
165
166
167
168
169
 
# File 'lib/ask-schema.rb', line 163

def method_missing(method_name, ...)
  if respond_to_missing?(method_name)
    self.class.send(method_name, ...)
  else
    super
  end
end

Class Method Details

.additional_properties(value = nil) ⇒ Boolean

Set or get whether additional (undeclared) properties are allowed.

Parameters:

  • value (Boolean, nil) (defaults to: nil) —

    True to allow additional properties

Returns:

  • (Boolean) —

    Defaults to false



100
101
102
103
104
 
# File 'lib/ask-schema.rb', line 100

def additional_properties(value = nil)
  return @additional_properties ||= false if value.nil?

  @additional_properties = value
end

.create(&block) ⇒ Class<Schema>

Create a new Schema subclass from a DSL block.

Examples:

schema = Ask::Schema.create do
  string :name
  integer :age
end

Parameters:

  • block (Proc) —

    DSL block with type definitions

Returns:

  • (Class<Schema>) —

    A dynamically-created Schema subclass



49
50
51
52
53
 
# File 'lib/ask-schema.rb', line 49

def create(&block)
  schema_class = Class.new(Schema)
  schema_class.class_eval(&block)
  schema_class
end

.definitions ⇒ Hash{Symbol => Hash}

Named sub-schema definitions for ‘$defs`.

Returns:

  • (Hash{Symbol => Hash}) —

    Named definitions keyed by symbol



72
73
74
 
# File 'lib/ask-schema.rb', line 72

def definitions
  @definitions ||= {}
end

.description(description = nil) ⇒ String?

Set or get the schema description used in JSON output.

Parameters:

  • description (String, nil) (defaults to: nil) —

    The schema description

Returns:

  • (String, nil) —

    The current description



91
92
93
94
 
# File 'lib/ask-schema.rb', line 91

def description(description = nil)
  @description = description if description
  @description
end

.name(name = nil) ⇒ String?

Set or get the schema name used in JSON output.

Parameters:

  • name (String, nil) (defaults to: nil) —

    The schema name

Returns:

  • (String, nil) —

    The current schema name



80
81
82
83
84
85
 
# File 'lib/ask-schema.rb', line 80

def name(name = nil)
  @schema_name = name if name
  return @schema_name if defined?(@schema_name)

  super()
end

.properties ⇒ Hash{Symbol => Hash}

Properties defined on this schema class (inheritable).

Returns:

  • (Hash{Symbol => Hash}) —

    Property definitions keyed by name



58
59
60
 
# File 'lib/ask-schema.rb', line 58

def properties
  @properties ||= {}
end

.required_properties ⇒ Array<Symbol>

Required property names for this schema class (inheritable).

Returns:

  • (Array<Symbol>) —

    Required property names



65
66
67
 
# File 'lib/ask-schema.rb', line 65

def required_properties
  @required_properties ||= []
end

.strict(*args) ⇒ Boolean

Set or get strict mode for the schema.

When strict, the schema includes ‘“strict”: true` in output.

Parameters:

  • args (Boolean, nil) —

    The strict mode value

Returns:

  • (Boolean) —

    Defaults to true



112
113
114
115
116
117
118
 
# File 'lib/ask-schema.rb', line 112

def strict(*args)
  if args.empty?
    instance_variable_defined?(:@strict) ? @strict : true
  else
    @strict = args.first
  end
end

.valid? ⇒ Boolean

Check if the schema definition is valid.

Returns:

  • (Boolean) —

    true if the schema has no validation errors



132
133
134
135
 
# File 'lib/ask-schema.rb', line 132

def valid?
  validator = Validator.new(self)
  validator.valid?
end

.validate! ⇒ nil

Validate the schema definition, raising on circular references or other errors.

Returns:

  • (nil) —

    if the schema is valid

Raises:



124
125
126
127
 
# File 'lib/ask-schema.rb', line 124

def validate!
  validator = Validator.new(self)
  validator.validate!
end

Instance Method Details

#respond_to_missing?(method_name, include_private = false) ⇒ Boolean

Check if a method can be delegated to the class level.

Returns:

  • (Boolean) 


172
173
174
 
# File 'lib/ask-schema.rb', line 172

def respond_to_missing?(method_name, include_private = false)
  %i[string number integer boolean array object any_of one_of null].include?(method_name) || super
end

#valid? ⇒ Boolean

Check if this schema instance is valid.

Returns:

  • (Boolean) 


158
159
160
 
# File 'lib/ask-schema.rb', line 158

def valid?
  self.class.valid?
end

#validate! ⇒ nil

Validate this schema instance.

Returns:

  • (nil) —

    if valid

Raises:



151
152
153
 
# File 'lib/ask-schema.rb', line 151

def validate!
  self.class.validate!
end