Element

GitHub

Block context for defining JSON blob structure in representation attributes.

Used inside attribute blocks to define the shape of JSON/JSONB columns, Rails store attributes, or any serialized data structure.

Only complex types are allowed at the top level:

• #object for key-value structures
• #array for ordered collections
• #union for polymorphic structures

Inside these blocks, the full type DSL is available including nested objects, arrays, primitives, and unions.

Example: Object structure

attribute :settings do
  object do
    string :theme
    boolean :notifications
    integer :max_items, min: 1, max: 100
  end
end

Example: Array of objects

attribute :addresses do
  array do
    object do
      string :street
      string :city
      string :zip
      boolean :primary
    end
  end
end

Example: Nested structures

attribute :config do
  object do
    string :name
    array :tags do
      string
    end
    object :metadata do
      datetime :created_at
      datetime :updated_at
    end
  end
end

Example: Union for polymorphic data

attribute :payment_details do
  union discriminator: :type do
    variant tag: 'card' do
      object do
        string :last_four
        string :brand
      end
    end
    variant tag: 'bank' do
      object do
        string :account_number
        string :routing_number
      end
    end
  end
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, &block)

GitHub

Defines the element type.

Only complex types (:object, :array, :union) are allowed.

Parameters

Name	Type	Default	Description
type	Symbol<:array, :object, :union>		The element type.
discriminator	Symbol, nil	nil	The discriminator field name. Unions only.

Returns

void

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

---

#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

---