Class: Apiwork::Representation::Element

Inherits:
Element
  • Object
show all
Defined in:
lib/apiwork/representation/element.rb

Overview

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:

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

Examples:

Object structure

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

Array of objects

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

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

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

See Also:

Instance Attribute Summary

Attributes inherited from Element

#custom_type, #discriminator, #enum, #format, #inner, #max, #min, #shape, #type, #value

Instance Method Summary collapse

Methods inherited from Element

#array, #binary, #boolean, #date, #datetime, #decimal, #initialize, #integer, #literal, #number, #object, #record, #reference, #string, #time, #union, #unknown, #uuid

Constructor Details

This class inherits a constructor from Apiwork::Element

Instance Method Details

#of(type, discriminator: nil) {|shape| ... } ⇒ void

This method returns an undefined value.

Defines the element type.

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

Parameters:

  • type (Symbol) —
    :array, :object, :record, :union

    The element type.

  • discriminator (Symbol, nil) (defaults to: nil) —

    (nil) The discriminator field name. Unions only.

Yields:

  • block for defining nested structure (instance_eval style)

Yield Parameters:

Raises:

  • (ArgumentError) —

    if object, array, or union type is missing block



94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/apiwork/representation/element.rb', line 94

def of(type, discriminator: nil, &block)
  case type
  when :object
    raise ConfigurationError, 'object requires a block' unless block

    builder = API::Object.new
    block.arity.positive? ? yield(builder) : builder.instance_eval(&block)
    @type = :object
    @shape = builder
    @defined = true
  when :array
    raise ConfigurationError, 'array requires a block' unless block

    inner = API::Element.new
    block.arity.positive? ? yield(inner) : inner.instance_eval(&block)
    inner.validate!
    @type = :array
    @inner = inner
    @shape = inner.shape
    @defined = true
  when :record
    raise ConfigurationError, 'record requires a block' unless block

    inner = API::Element.new
    block.arity.positive? ? yield(inner) : inner.instance_eval(&block)
    inner.validate!
    @type = :record
    @inner = inner
    @defined = true
  when :union
    raise ConfigurationError, 'union requires a block' unless block

    builder = API::Union.new(discriminator:)
    block.arity.positive? ? yield(builder) : builder.instance_eval(&block)
    @type = :union
    @shape = builder
    @discriminator = discriminator
    @defined = true
  else
    raise ConfigurationError, "Representation::Element only supports :object, :array, :record, :union - got #{type.inspect}"
  end
end

#validate! ⇒ Object

Raises:



77
78
79
 
# File 'lib/apiwork/representation/element.rb', line 77

def validate!
  raise ConfigurationError, 'must define exactly one type (object, array, record, or union)' unless @defined
end