apiwork 0.4.0 → 0.6.0

data/lib/apiwork/representation/base.rb

@@ -69,6 +69,7 @@ module Apiwork
       class_attribute :inheritance, default: nil, instance_accessor: false
 
       class_attribute :_adapter_config, default: {}, instance_accessor: false
+      class_attribute :type_definitions, default: {}, instance_accessor: false
 
       # @!attribute [r] context
       #   @api public
@@ -540,6 +541,110 @@ module Apiwork
           )
         end
 
+        # @api public
+        # Defines an object type for this representation.
+        #
+        # The type is copied to the contract that uses this representation. Attributes can reference
+        # it by name via `type:`. In exports, the type is scoped to the contract.
+        #
+        # @param name [Symbol]
+        #   The object name.
+        # @param deprecated [Boolean] (false)
+        #   Whether deprecated. Metadata included in exports.
+        # @param description [String, nil] (nil)
+        #   The description. Metadata included in exports.
+        # @param example [Object, nil] (nil)
+        #   The example. Metadata included in exports.
+        # @yieldparam object [API::Object]
+        # @return [void]
+        #
+        # @example Define and reference
+        #   object :address do
+        #     string :street
+        #     string :city
+        #     string :postal_code
+        #   end
+        #
+        #   attribute :shipping_address, type: :address
+        #   attribute :billing_address, type: :address
+        def object(
+          name,
+          deprecated: false,
+          description: nil,
+          example: nil,
+          &block
+        )
+          self.type_definitions = type_definitions.merge(
+            name.to_sym => {
+              block:,
+              kind: :object,
+              options: {
+                deprecated:,
+                description:,
+                example:,
+              },
+            },
+          )
+        end
+
+        # @api public
+        # Defines a union type for this representation.
+        #
+        # The type is copied to the contract that uses this representation. Attributes can reference
+        # it by name via `type:`. In exports, the type is scoped to the contract.
+        #
+        # @param name [Symbol]
+        #   The union name.
+        # @param deprecated [Boolean] (false)
+        #   Whether deprecated. Metadata included in exports.
+        # @param description [String, nil] (nil)
+        #   The description. Metadata included in exports.
+        # @param discriminator [Symbol, nil] (nil)
+        #   The discriminator field name.
+        # @param example [Object, nil] (nil)
+        #   The example. Metadata included in exports.
+        # @yieldparam union [API::Union]
+        # @return [void]
+        #
+        # @example Define and reference
+        #   union :content_block, discriminator: :kind do
+        #     variant tag: 'text' do
+        #       object do
+        #         string :body
+        #       end
+        #     end
+        #     variant tag: 'image' do
+        #       object do
+        #         string :url
+        #         integer :width
+        #         integer :height
+        #       end
+        #     end
+        #   end
+        #
+        #   attribute :content, type: :content_block
+        def union(
+          name,
+          deprecated: false,
+          description: nil,
+          discriminator: nil,
+          example: nil,
+          &block
+        )
+          self.type_definitions = type_definitions.merge(
+            name.to_sym => {
+              block:,
+              kind: :union,
+              options: {
+                deprecated:,
+                description:,
+                discriminator:,
+                example:,
+              },
+            },
+          )
+        end
+
         # @api public
         # The type name for this representation.
         #

data/lib/apiwork/representation/element.rb

@@ -11,10 +11,11 @@ module Apiwork
     # Only complex types are allowed at the top level:
     # - {#object} for key-value structures
     # - {#array} for ordered collections
+    # - {#record} for key-value maps with typed values
     # - {#union} for polymorphic structures
     #
     # Inside these blocks, the full type DSL is available including
-    # nested objects, arrays, primitives, and unions.
+    # nested objects, arrays, records, primitives, and unions.
     #
     # @see API::Element Block context for array elements
     # @see API::Object Block context for object fields
@@ -74,15 +75,15 @@ module Apiwork
     #   end
     class Element < Apiwork::Element
       def validate!
-        raise ConfigurationError, 'must define exactly one type (object, array, or union)' unless @defined
+        raise ConfigurationError, 'must define exactly one type (object, array, record, or union)' unless @defined
       end
 
       # @api public
       # Defines the element type.
       #
-      # Only complex types (:object, :array, :union) are allowed.
+      # Only complex types (:object, :array, :record, :union) are allowed.
       #
-      # @param type [Symbol] [:array, :object, :union]
+      # @param type [Symbol] [:array, :object, :record, :union]
       #   The element type.
       # @param discriminator [Symbol, nil] (nil)
       #   The discriminator field name. Unions only.
@@ -110,6 +111,15 @@ module Apiwork
           @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
 
@@ -120,7 +130,7 @@ module Apiwork
           @discriminator = discriminator
           @defined = true
         else
-          raise ConfigurationError, "Representation::Element only supports :object, :array, :union - got #{type.inspect}"
+          raise ConfigurationError, "Representation::Element only supports :object, :array, :record, :union - got #{type.inspect}"
         end
       end
     end

data/lib/apiwork/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Apiwork
-  VERSION = '0.4.0'
+  VERSION = '0.6.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apiwork
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - skiftle
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-09 00:00:00.000000000 Z
+date: 2026-04-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -261,6 +261,7 @@ files:
 - lib/apiwork/error_code/registry.rb
 - lib/apiwork/export.rb
 - lib/apiwork/export/base.rb
+- lib/apiwork/export/builder_mapper.rb
 - lib/apiwork/export/open_api.rb
 - lib/apiwork/export/pipeline.rb
 - lib/apiwork/export/pipeline/writer.rb
@@ -306,6 +307,7 @@ files:
 - lib/apiwork/introspection/param/literal.rb
 - lib/apiwork/introspection/param/number.rb
 - lib/apiwork/introspection/param/object.rb
+- lib/apiwork/introspection/param/record.rb
 - lib/apiwork/introspection/param/reference.rb
 - lib/apiwork/introspection/param/string.rb
 - lib/apiwork/introspection/param/time.rb