module Jimmy::Declaration
Contains methods for declaring or modifying schemas.
Constants
- BOOLEANS
- CASTABLE_CLASSES
- CASTS
- FORMATS
- SIMPLE_TYPES
Acceptable values for
#type
.
Public Instance Methods
Set the allOf
value for the schema. @param [Array<Jimmy::Schema>] schemas The schemas to set as the value of
+allOf+.
@return [self] self, for chaining
# File lib/jimmy/declaration/composites.rb, line 17 def all_of(*schemas) set_composite 'allOf', schemas.flatten end
Set the anyOf
value for the schema. @param [Array<Jimmy::Schema>] schemas The schemas to set as the value of
+anyOf+.
@return [self] self, for chaining
# File lib/jimmy/declaration/composites.rb, line 9 def any_of(*schemas) set_composite 'anyOf', schemas.flatten end
Set a constant value that will be expected to match exactly. @param [Object] constant_value The value that will be expected to match
exactly.
@return [self] self, for chaining
# File lib/jimmy/declaration.rb, line 59 def const(constant_value) set const: constant_value end
Set the default value for the schema. @param [Object] default The default value for the schema. @return [self] self, for chaining
# File lib/jimmy/declaration.rb, line 35 def default(default) set default: default end
Add a schema to this schema's definitions
property. @param [String] name The name of the schema definition. @param [Jimmy::Schema] schema @yieldparam schema [Jimmy::Schema] The defined schema. @return [self] self, for chaining
# File lib/jimmy/declaration.rb, line 87 def define(name, schema = Schema.new, &block) return definitions name, &block if name.is_a? Hash assign_to_schema_hash 'definitions', name, schema, &block end
Add definitions to the schema's definitions
property. @param [Hash{String => Jimmy::Schema
, nil}] definitions Definitions to be
added to the schema's +definitions+ property.
@yieldparam name [String] The name of a definition that was given a nil
schema.
@yieldparam schema [Jimmy::Schema] A new schema created in place of a
nil hash value.
@return [self] self, for chaining
# File lib/jimmy/declaration.rb, line 101 def definitions(definitions, &block) batch_assign_to_schema_hash 'definitions', definitions, &block end
Set the description of the schema. @param [String] description The description of the schema. @return [self] self, for chaining
# File lib/jimmy/declaration.rb, line 27 def description(description) assert_string description set description: description end
Set an enum value for the schema. @param [Array, Set] allowed_values The allowed values in the enum. @return [self] self, for chaining
# File lib/jimmy/declaration.rb, line 66 def enum(allowed_values) allowed_values = allowed_values.to_a if allowed_values.is_a? Set assert_array allowed_values, minimum: 1, unique: true set enum: allowed_values end
Add examples to the schema @param [Array] examples One or more examples to add to the schema. @return [self] self, for chaining
# File lib/jimmy/declaration.rb, line 75 def examples(*examples) getset('examples') { [] }.concat examples self end
Define the schema that determines whether the then
or else
schemas must be valid. @param schema [Schema] The if
schema. @param then_schema [Schema] The then
schema. @param else_schema [Schema] The else
schema. @return [self] self, for chaining
# File lib/jimmy/declaration/conditions.rb, line 11 def if(schema, then_schema = nil, else_schema = nil) set(if: cast_schema(schema)).tap do |s| s.then then_schema unless then_schema.nil? s.else else_schema unless else_schema.nil? end end
Set the number of which the value should be a multiple. @param [Numeric] number The number to set as the multipleOf value @return [self] self, for chaining
# File lib/jimmy/declaration/number.rb, line 8 def multiple_of(number) valid_for 'number', 'integer' assert_numeric number assert(number.positive?) { "Expected #{number} to be positive" } set multipleOf: number end
Define the schema that this schema must not match. @param schema [Jimmy::Schema] The schema that must not match. @return [self] self, for chaining
# File lib/jimmy/declaration.rb, line 108 def not(schema) # TODO: combine more nots into an anyOf set not: cast_schema(schema) end
Set the oneOf
value for the schema. @param [Array<Jimmy::Schema>] schemas The schemas to set as the value of
+oneOf+.
@return [self] self, for chaining
# File lib/jimmy/declaration/composites.rb, line 25 def one_of(*schemas) set_composite 'oneOf', schemas.flatten end
Set the pattern for a string value. @param [Regexp] expression The pattern for a string value. Cannot include
any options such as +/i+.
@return [self] self, for chaining
# File lib/jimmy/declaration/string.rb, line 31 def pattern(expression) assert_regexp expression set(pattern: expression.source).string end
Set minimum and maximum by providing a range. @param [Range] range The range to use for minimum and maximum values. @return [self] self, for chaining
# File lib/jimmy/declaration/number.rb, line 18 def range(range) assert_range range schema do |s| s.type range.begin.is_a?(Integer) ? 'integer' : 'number' s.minimum range.begin s.maximum range.end, exclusive: range.exclude_end? unless range.end.nil? end end
Set whether the schema is read-only. @param [true, false] is_read_only @return [self] self, for chaining
# File lib/jimmy/declaration.rb, line 42 def read_only(is_read_only = true) assert_boolean is_read_only set readOnly: is_read_only end
Shortcut for +object.additional_properties(false)+. @return [Jimmy::Schema]
# File lib/jimmy/declaration/object.rb, line 7 def struct object.additional_properties false end
Set the title of the schema. @param [String] title The title of the schema. @return [self] self, for chaining
# File lib/jimmy/declaration.rb, line 19 def title(title) assert_string title set title: title end
Set the type(s) of the schema. @param [String, Array<String>] types The type(s) of the schema. @return [self] self, for chaining
# File lib/jimmy/declaration/types.rb, line 12 def type(*types) types = types.flatten types.each &method(:assert_simple_type) assert_array types, unique: true, minimum: 1 types = Array(get('type') { [] }) | types.flatten types = types.first if types.one? set type: types end
Set whether the schema is write-only. @param [true, false] is_write_only @return [self] self, for chaining
# File lib/jimmy/declaration.rb, line 50 def write_only(is_write_only = true) assert_boolean is_write_only set writeOnly: is_write_only end
Private Instance Methods
# File lib/jimmy/declaration/casting.rb, line 28 def apply_cast(schema, value) CASTS.each do |klass, proc| return proc.call schema, value if value.is_a? klass end end
# File lib/jimmy/declaration/assertion.rb, line 11 def assert(condition = false) raise Error::InvalidSchemaPropertyValue, yield unless condition end
# File lib/jimmy/declaration/assertion.rb, line 37 def assert_array(value, unique: false, minimum: 0) assert(value.is_a? Array) { "Expected #{value.class} to be an array" } assert(value.uniq == value) { 'Expected a unique array' } if unique assert value.length >= minimum do "Expected an array of at least #{minimum} item(s)" end end
# File lib/jimmy/declaration/assertion.rb, line 31 def assert_boolean(value) assert BOOLEANS.include? value do "Expected #{value.class} to be boolean" end end
# File lib/jimmy/declaration/assertion.rb, line 45 def assert_hash(value) assert(value.is_a? Hash) { "Expected #{value.class} to be a hash" } end
# File lib/jimmy/declaration/assertion.rb, line 15 def assert_numeric(value, minimum: -Float::INFINITY) assert(value.is_a? Numeric) { "Expected #{value.class} to be numeric" } assert(value >= minimum) { "Expected #{value} to be at least #{minimum}" } end
# File lib/jimmy/declaration/assertion.rb, line 49 def assert_range(value) assert(value.is_a? Range) { "Expected #{value.class} to be a range " } end
# File lib/jimmy/declaration/assertion.rb, line 53 def assert_regexp(value) assert value.is_a? Regexp do "Expected #{value.class} to be regular expression" end assert value.options.zero? do "Expected #{value.inspect} not to have any options" end end
# File lib/jimmy/declaration/assertion.rb, line 24 def assert_simple_type(value) assert_string value assert SIMPLE_TYPES.include?(value) do "Expected #{value.class} to be one of #{SIMPLE_TYPES.to_a.join ', '}" end end
# File lib/jimmy/declaration/assertion.rb, line 20 def assert_string(value) assert(value.is_a? String) { "Expected #{value.class} to be a string" } end
# File lib/jimmy/declaration.rb, line 126 def assign_to_schema_hash(property_name, key, schema) property_name = cast_key(property_name) key = cast_key(key) hash = getset(property_name) { {} } schema = cast_schema(schema) yield schema if block_given? hash[key] = schema self end
# File lib/jimmy/declaration.rb, line 136 def batch_assign_to_schema_hash(property_name, hash) assert_hash hash hash.each do |name, schema| name = cast_key(name) if schema.nil? && block_given? schema = Schema.new yield name, schema end assign_to_schema_hash property_name, name, schema end self end
Cast the given value to a usable schema. @param [Object] value @return [Jimmy::Schema]
# File lib/jimmy/declaration/casting.rb, line 19 def cast_schema(value) case value when *CASTABLE_CLASSES then apply_cast(Schema.new, value) when Schema then value else assert { "Expected #{value.class} to be a schema" } end end
# File lib/jimmy/declaration.rb, line 121 def getset(name) set name => yield unless key? name get name end
# File lib/jimmy/declaration.rb, line 115 def set(props) s = schema props.each { |k, v| s[k.to_s] = v } s end
@return [self]
# File lib/jimmy/declaration/composites.rb, line 32 def set_composite(name, schemas) assert_array schemas, minimum: 1 schemas = schemas.map(&method(:cast_schema)) assert schemas.none? { |s| s.anything? || s.nothing? } do 'Absolutes make no sense in composites' end set name => schemas end
Returns true if one of the given types is an existing type. @param [Array<String>] types The type or types to check. @return [true, false]
# File lib/jimmy/declaration/assertion.rb, line 71 def type?(*types) types.each &method(:assert_simple_type) existing = get('type', nil) if existing.is_a? Json::Array (existing.to_a & types).any? else types.include? existing end end
# File lib/jimmy/declaration/assertion.rb, line 62 def valid_for(*types) assert type? *types do "The property is only valid for #{types.join ', '} schemas" end end