Element

GitHub

Block context for defining a single type expression.

Used inside array do and variant do blocks where exactly one element type must be defined.

Example: instance_eval style

array :ids do
  integer
end

Example: yield style

array :ids do |element|
  element.integer
end

Example: Array of references

array :items do |element|
  element.reference :item
end

Instance Methods

#array

#array(&block)

GitHub

Defines an array.

Returns

void

Yields Element

Example: instance_eval style

array :matrix do
  array do
    integer
  end
end

Example: yield style

array :matrix do |element|
  element.array do |inner|
    inner.integer
  end
end

---

#binary

#binary

GitHub

Defines a binary.

Returns

void

Example

array :blobs do
  binary
end

---

#boolean

#boolean

GitHub

Defines a boolean.

Returns

void

Example

array :flags do
  boolean
end

---

#custom_type

#custom_type

GitHub

The custom type name for this element.

Returns

Symbol, nil

---

#date

#date

GitHub

Defines a date.

Returns

void

Example

array :dates do
  date
end

---

#datetime

#datetime

GitHub

Defines a datetime.

Returns

void

Example

array :timestamps do
  datetime
end

---

#decimal

#decimal(max: nil, min: nil)

GitHub

Defines a decimal.

Parameters

Name	Type	Default	Description
max	Numeric, nil	nil	The maximum value.
min	Numeric, nil	nil	The minimum value.

Returns

void

Example: Basic decimal

array :amounts do
  decimal
end

Example: With range constraints

array :prices do
  decimal min: 0
end

---

#discriminator

#discriminator

GitHub

The discriminator for this element.

Returns

Symbol, nil

---

#enum

#enum

GitHub

The allowed values for this element.

Returns

Array, Symbol, nil

---

#format

#format

GitHub

The format hint for this element.

Returns

Symbol, nil

---

#inner

#inner

GitHub

The inner element for nested arrays.

Returns

Element, nil

---

#integer

#integer(enum: nil, max: nil, min: nil)

GitHub

Defines an integer.

Parameters

Name	Type	Default	Description
enum	Array, Symbol, nil	nil	The allowed values.
max	Integer, nil	nil	The maximum value.
min	Integer, nil	nil	The minimum value.

Returns

void

Example: Basic integer

array :counts do
  integer
end

Example: With range constraints

array :scores do
  integer min: 0, max: 100
end

---

#literal

#literal(value:)

GitHub

Defines a literal value.

Parameters

Name	Type	Default	Description
value	Object		The literal value.

Returns

void

Example

variant tag: 'card' do
  literal value: 'card'
end

---

#max

#max

GitHub

The maximum constraint for this element.

Returns

Numeric, nil

---

#min

#min

GitHub

The minimum constraint for this element.

Returns

Numeric, nil

---

#number

#number(max: nil, min: nil)

GitHub

Defines a number.

Parameters

Name	Type	Default	Description
max	Numeric, nil	nil	The maximum value.
min	Numeric, nil	nil	The minimum value.

Returns

void

Example: Basic number

array :coordinates do
  number
end

Example: With range constraints

array :latitudes do
  number min: -90, max: 90
end

---

#object

#object(&block)

GitHub

Defines an object.

Returns

void

Yields Object

Example: instance_eval style

array :items do
  object do
    string :name
    decimal :price
  end
end

Example: yield style

array :items do |element|
  element.object do |object|
    object.string :name
    object.decimal :price
  end
end

---

#of

#of(type, discriminator: nil, enum: nil, format: nil, max: nil, min: nil, value: nil, &block)

GitHub

Defines the element type.

This is the verbose form. Prefer sugar methods (string, integer, etc.) for static definitions. Use of for dynamic element generation.

Parameters

Name	Type	Default	Description
type	Symbol<:array, :binary, :boolean, :date, :datetime, :decimal, :integer, :literal, :number, :object, :string, :time, :union, :uuid>		The element type. Custom type references are also allowed.
discriminator	Symbol, nil	nil	The discriminator field name. Unions only.
enum	Array, Symbol, nil	nil	The allowed values. Strings and integers only.
format	Symbol<:date, :datetime, :double, :email, :float, :hostname, :int32, :int64, :ipv4, :ipv6, :password, :url, :uuid>, nil	nil	Format hint for exports. Does not change the type, but exports may add validation or documentation based on it. Valid formats by type: :decimal/:number (:double, :float), :integer (:int32, :int64), :string (:date, :datetime, :email, :hostname, :ipv4, :ipv6, :password, :url, :uuid).
max	Integer, nil	nil	The maximum. For :decimal, :integer, :number: value. For :string: length.
min	Integer, nil	nil	The minimum. For :decimal, :integer, :number: value. For :string: length.
value	Object, nil	nil	The literal value. Literals only.

Returns

void

Yields API::Object, API::Union, API::Element

Example: Dynamic element type

element_type = :string
array :values do
  of element_type
end

Example: Object with block

array :tags do
  of :object do
    string :name
  end
end

---

#reference

#reference(type_name)

GitHub

Defines a reference to a named type.

Parameters

Name	Type	Default	Description
type_name	Symbol		The type to reference.

Returns

void

Example

array :items do
  reference :item
end

---

#shape

#shape

GitHub

The shape for this element.

Returns

Object, nil

---

#string

#string(enum: nil, format: nil, max: nil, min: nil)

GitHub

Defines a string.

Parameters

Name	Type	Default	Description
enum	Array, Symbol, nil	nil	The allowed values.
format	Symbol<:date, :datetime, :email, :hostname, :ipv4, :ipv6, :password, :url, :uuid>, nil	nil	Format hint for exports. Does not change the type, but exports may add validation or documentation based on it. Valid formats by type: :string.
max	Integer, nil	nil	The maximum length.
min	Integer, nil	nil	The minimum length.

Returns

void

Example: Basic string

array :tags do
  string
end

Example: With length constraints

array :tags do
  string min: 1, max: 50
end

---

#time

#time

GitHub

Defines a time.

Returns

void

Example

array :times do
  time
end

---

#type

#type

GitHub

The type for this element.

Returns

Symbol, nil

---

#union

#union(discriminator: nil, &block)

GitHub

Defines a union.

Parameters

Name	Type	Default	Description
discriminator	Symbol, nil	nil	The discriminator field name.

Returns

void

Yields Union

Example: instance_eval style

array :payments do
  union discriminator: :type do
    variant tag: 'card' do
      object do
        string :last_four
      end
    end
  end
end

Example: yield style

array :payments do |element|
  element.union discriminator: :type do |union|
    union.variant tag: 'card' do |variant|
      variant.object do |object|
        object.string :last_four
      end
    end
  end
end

---

#uuid

#uuid

GitHub

Defines a UUID.

Returns

void

Example

array :ids do
  uuid
end

---