Module: Jimmy::Declaration

Included in:
Macros, Schema
Defined in:
lib/jimmy/declaration.rb,
lib/jimmy/declaration/types.rb,
lib/jimmy/declaration/number.rb,
lib/jimmy/declaration/object.rb,
lib/jimmy/declaration/string.rb,
lib/jimmy/declaration/casting.rb,
lib/jimmy/declaration/assertion.rb,
lib/jimmy/declaration/composites.rb,
lib/jimmy/declaration/conditions.rb

Overview

Contains methods for declaring or modifying schemas.

Constant Summary collapse

SIMPLE_TYPES =

Acceptable values for #type.

Set.new(%w[array boolean integer null number object string]).freeze
FORMATS = 
Set.new(
  %w[
    date-time
    date
    time
    email
    idn-email
    hostname
    idn-hostname
    ipv4
    ipv6
    uri
    uri-reference
    iri
    iri-reference
    uri-template
    json-pointer
    relative-json-pointer
    regex
  ]
).freeze
BOOLEANS = 
Set.new([true, false]).freeze

Instance Method Summary collapse

Instance Method Details

#all_of(*schemas) ⇒ self

Set the allOf value for the schema.

Parameters:

  • schemas (Array<Jimmy::Schema>) —

    The schemas to set as the value of allOf.

Returns:

  • (self) —

    self, for chaining



17
18
19
 
# File 'lib/jimmy/declaration/composites.rb', line 17

def all_of(*schemas)
  set_composite 'allOf', schemas.flatten
end

#any_of(*schemas) ⇒ self

Set the anyOf value for the schema.

Parameters:

  • schemas (Array<Jimmy::Schema>) —

    The schemas to set as the value of anyOf.

Returns:

  • (self) —

    self, for chaining



9
10
11
 
# File 'lib/jimmy/declaration/composites.rb', line 9

def any_of(*schemas)
  set_composite 'anyOf', schemas.flatten
end

#array ⇒ Schema

Make the schema allow type “array”.

Returns:




# File 'lib/jimmy/declaration/types.rb', line 33

#boolean ⇒ Schema

Make the schema allow type “boolean”.

Returns:




# File 'lib/jimmy/declaration/types.rb', line 33

#const(constant_value) ⇒ self

Set a constant value that will be expected to match exactly.

Parameters:

  • constant_value (Object) —

    The value that will be expected to match exactly.

Returns:

  • (self) —

    self, for chaining



59
60
61
 
# File 'lib/jimmy/declaration.rb', line 59

def const(constant_value)
  set const: constant_value
end

#date ⇒ Schema

Validate a string with format “date”.

Returns:




# File 'lib/jimmy/declaration/string.rb', line 44

#date_time ⇒ Schema

Validate a string with format “date-time”.

Returns:




# File 'lib/jimmy/declaration/string.rb', line 44

#default(default) ⇒ self

Set the default value for the schema.

Parameters:

  • default (Object) —

    The default value for the schema.

Returns:

  • (self) —

    self, for chaining



35
36
37
 
# File 'lib/jimmy/declaration.rb', line 35

def default(default)
  set default: default
end

#define(name, schema = Schema.new) {|schema| ... } ⇒ self

Add a schema to this schema’s definitions property.

Parameters:

  • name (String) —

    The name of the schema definition.

  • schema (Jimmy::Schema) (defaults to: Schema.new)

Yield Parameters:

Returns:

  • (self) —

    self, for chaining



87
88
89
90
91
 
# 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

#definitions(definitions) {|name, schema| ... } ⇒ self

Add definitions to the schema’s definitions property.

Parameters:

  • definitions (Hash{String => Jimmy::Schema, nil}) —

    Definitions to be added to the schema’s definitions property.

Yield Parameters:

  • name (String) —

    The name of a definition that was given a nil schema.

  • schema (Jimmy::Schema) —

    A new schema created in place of a nil hash value.

Returns:

  • (self) —

    self, for chaining



101
102
103
 
# File 'lib/jimmy/declaration.rb', line 101

def definitions(definitions, &block)
  batch_assign_to_schema_hash 'definitions', definitions, &block
end

#description(description) ⇒ self

Set the description of the schema.

Parameters:

  • description (String) —

    The description of the schema.

Returns:

  • (self) —

    self, for chaining



27
28
29
30
 
# File 'lib/jimmy/declaration.rb', line 27

def description(description)
  assert_string description
  set description: description
end

#email ⇒ Schema

Validate a string with format “email”.

Returns:




# File 'lib/jimmy/declaration/string.rb', line 44

#enum(allowed_values) ⇒ self

Set an enum value for the schema.

Parameters:

  • allowed_values (Array, Set) —

    The allowed values in the enum.

Returns:

  • (self) —

    self, for chaining



66
67
68
69
70
 
# 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

#examples(*examples) ⇒ self Also known as: example

Add examples to the schema

Parameters:

  • examples (Array) —

    One or more examples to add to the schema.

Returns:

  • (self) —

    self, for chaining



75
76
77
78
 
# File 'lib/jimmy/declaration.rb', line 75

def examples(*examples)
  getset('examples') { [] }.concat examples
  self
end

#hostname ⇒ Schema

Validate a string with format “hostname”.

Returns:




# File 'lib/jimmy/declaration/string.rb', line 44

#idn_email ⇒ Schema

Validate a string with format “idn-email”.

Returns:




# File 'lib/jimmy/declaration/string.rb', line 44

#idn_hostname ⇒ Schema

Validate a string with format “idn-hostname”.

Returns:




# File 'lib/jimmy/declaration/string.rb', line 44

#if(schema, then_schema = nil, else_schema = nil) ⇒ self

Define the schema that determines whether the then or else schemas must be valid.

Parameters:

  • schema (Schema) —

    The if schema.

  • then_schema (Schema) (defaults to: nil) —

    The then schema.

  • else_schema (Schema) (defaults to: nil) —

    The else schema.

Returns:

  • (self) —

    self, for chaining



11
12
13
14
15
16
 
# 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

#integer ⇒ Schema

Make the schema allow type “integer”.

Returns:




# File 'lib/jimmy/declaration/types.rb', line 33

#ipv4 ⇒ Schema

Validate a string with format “ipv4”.

Returns:




# File 'lib/jimmy/declaration/string.rb', line 44

#ipv6 ⇒ Schema

Validate a string with format “ipv6”.

Returns:




# File 'lib/jimmy/declaration/string.rb', line 44

#iri ⇒ Schema

Validate a string with format “iri”.

Returns:




# File 'lib/jimmy/declaration/string.rb', line 44

#iri_reference ⇒ Schema

Validate a string with format “iri-reference”.

Returns:




# File 'lib/jimmy/declaration/string.rb', line 44

#json_pointer ⇒ Schema

Validate a string with format “json-pointer”.

Returns:




# File 'lib/jimmy/declaration/string.rb', line 44

#multiple_of(number) ⇒ self

Set the number of which the value should be a multiple.

Parameters:

  • number (Numeric) —

    The number to set as the multipleOf value

Returns:

  • (self) —

    self, for chaining



8
9
10
11
12
13
 
# 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

#not(schema) ⇒ self

Define the schema that this schema must not match.

Parameters:

Returns:

  • (self) —

    self, for chaining



108
109
110
111
 
# File 'lib/jimmy/declaration.rb', line 108

def not(schema)
  # TODO: combine more nots into an anyOf
  set not: cast_schema(schema)
end

#null ⇒ Schema Also known as: nullable

Make the schema allow type “null”.

Returns:




# File 'lib/jimmy/declaration/types.rb', line 33

#number ⇒ Schema

Make the schema allow type “number”.

Returns:




# File 'lib/jimmy/declaration/types.rb', line 33

#object ⇒ Schema

Make the schema allow type “object”.

Returns:




# File 'lib/jimmy/declaration/types.rb', line 33

#one_of(*schemas) ⇒ self

Set the oneOf value for the schema.

Parameters:

  • schemas (Array<Jimmy::Schema>) —

    The schemas to set as the value of oneOf.

Returns:

  • (self) —

    self, for chaining



25
26
27
 
# File 'lib/jimmy/declaration/composites.rb', line 25

def one_of(*schemas)
  set_composite 'oneOf', schemas.flatten
end

#pattern(expression) ⇒ self

Set the pattern for a string value.

Parameters:

  • expression (Regexp) —

    The pattern for a string value. Cannot include any options such as /i.

Returns:

  • (self) —

    self, for chaining



31
32
33
34
 
# File 'lib/jimmy/declaration/string.rb', line 31

def pattern(expression)
  assert_regexp expression
  set(pattern: expression.source).string
end

#range(range) ⇒ self

Set minimum and maximum by providing a range.

Parameters:

  • range (Range) —

    The range to use for minimum and maximum values.

Returns:

  • (self) —

    self, for chaining



18
19
20
21
22
23
24
25
 
# 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

#read_only(is_read_only = true) ⇒ self

Set whether the schema is read-only.

Parameters:

  • is_read_only (true, false) (defaults to: true)

Returns:

  • (self) —

    self, for chaining



42
43
44
45
 
# 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

#regex ⇒ Schema

Validate a string with format “regex”.

Returns:




# File 'lib/jimmy/declaration/string.rb', line 44

#relative_json_pointer ⇒ Schema

Validate a string with format “relative-json-pointer”.

Returns:




# File 'lib/jimmy/declaration/string.rb', line 44

#string ⇒ Schema

Make the schema allow type “string”.

Returns:




# File 'lib/jimmy/declaration/types.rb', line 33

#struct ⇒ Jimmy::Schema

Shortcut for object.additional_properties(false).

Returns:



7
8
9
 
# File 'lib/jimmy/declaration/object.rb', line 7

def struct
  object.additional_properties false
end

#time ⇒ Schema

Validate a string with format “time”.

Returns:




# File 'lib/jimmy/declaration/string.rb', line 44

#title(title) ⇒ self

Set the title of the schema.

Parameters:

  • title (String) —

    The title of the schema.

Returns:

  • (self) —

    self, for chaining



19
20
21
22
 
# File 'lib/jimmy/declaration.rb', line 19

def title(title)
  assert_string title
  set title: title
end

#type(*types) ⇒ self Also known as: types

Set the type(s) of the schema.

Parameters:

  • types (String, Array<String>) —

    The type(s) of the schema.

Returns:

  • (self) —

    self, for chaining



12
13
14
15
16
17
18
19
 
# 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

#uri ⇒ Schema

Validate a string with format “uri”.

Returns:




# File 'lib/jimmy/declaration/string.rb', line 44

#uri_reference ⇒ Schema

Validate a string with format “uri-reference”.

Returns:




# File 'lib/jimmy/declaration/string.rb', line 44

#uri_template ⇒ Schema

Validate a string with format “uri-template”.

Returns:




# File 'lib/jimmy/declaration/string.rb', line 44

#write_only(is_write_only = true) ⇒ self

Set whether the schema is write-only.

Parameters:

  • is_write_only (true, false) (defaults to: true)

Returns:

  • (self) —

    self, for chaining



50
51
52
53
 
# 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