apiwork 0.3.1 → 0.5.0

data/lib/apiwork/object.rb

@@ -71,7 +71,7 @@ module Apiwork
     #   The allowed values.
     # @param example [String, nil] (nil)
     #   The example value. Metadata included in exports.
-    # @param format [Symbol, nil] (nil) [:date, :datetime, :email, :hostname, :ipv4, :ipv6, :password, :url, :uuid]
+    # @param format [Symbol, nil] (nil) [:date, :datetime, :email, :hostname, :ipv4, :ipv6, :password, :text, :url, :uuid]
     #   Format hint for exports. Does not change the type, but exports may add validation or documentation based on it.
     #   Valid formats by type: `:string`.
     # @param max [Integer, nil] (nil)
@@ -144,7 +144,7 @@ module Apiwork
     #   The allowed values.
     # @param example [String, nil] (nil)
     #   The example value. Metadata included in exports.
-    # @param format [Symbol, nil] (nil) [:date, :datetime, :email, :hostname, :ipv4, :ipv6, :password, :url, :uuid]
+    # @param format [Symbol, nil] (nil) [:date, :datetime, :email, :hostname, :ipv4, :ipv6, :password, :text, :url, :uuid]
     #   Format hint for exports. Does not change the type, but exports may add validation or documentation based on it.
     #   Valid formats by type: `:string`.
     # @param max [Integer, nil] (nil)
@@ -1129,6 +1129,103 @@ module Apiwork
       )
     end
 
+    # @api public
+    # Defines an unknown.
+    #
+    # @param name [Symbol]
+    #   The name.
+    # @param as [Symbol, nil] (nil)
+    #   The target attribute name.
+    # @param default [Object, nil] (nil)
+    #   The default value.
+    # @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 value. Metadata included in exports.
+    # @param nullable [Boolean] (false)
+    #   Whether the value can be `null`.
+    # @param optional [Boolean] (false)
+    #   Whether the param is optional.
+    # @param required [Boolean] (false)
+    #   Whether the param is required.
+    # @return [void]
+    #
+    # @example Opaque metadata
+    #   unknown :metadata
+    def unknown(
+      name,
+      as: nil,
+      default: nil,
+      deprecated: false,
+      description: nil,
+      example: nil,
+      nullable: false,
+      optional: false,
+      required: false
+    )
+      param(
+        name,
+        as:,
+        default:,
+        deprecated:,
+        description:,
+        example:,
+        nullable:,
+        optional:,
+        required:,
+        type: :unknown,
+      )
+    end
+
+    # @api public
+    # Defines an optional unknown.
+    #
+    # @param name [Symbol]
+    #   The name.
+    # @param as [Symbol, nil] (nil)
+    #   The target attribute name.
+    # @param default [Object, nil] (nil)
+    #   The default value.
+    # @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 value. Metadata included in exports.
+    # @param nullable [Boolean] (false)
+    #   Whether the value can be `null`.
+    # @param required [Boolean] (false)
+    #   Whether the param is required.
+    # @return [void]
+    #
+    # @example Optional metadata
+    #   unknown? :metadata
+    def unknown?(
+      name,
+      as: nil,
+      default: nil,
+      deprecated: false,
+      description: nil,
+      example: nil,
+      nullable: false,
+      required: false
+    )
+      param(
+        name,
+        as:,
+        default:,
+        deprecated:,
+        description:,
+        example:,
+        nullable:,
+        required:,
+        optional: true,
+        type: :unknown,
+      )
+    end
+
     # @api public
     # Defines an object.
     #
@@ -1267,6 +1364,22 @@ module Apiwork
     #       decimal :price
     #     end
     #   end
+    #
+    # @example Array of discriminated union
+    #   array :notifications do
+    #     union discriminator: :type do
+    #       variant tag: 'email' do
+    #         object do
+    #           string :address
+    #         end
+    #       end
+    #       variant tag: 'sms' do
+    #         object do
+    #           string :phone
+    #         end
+    #       end
+    #     end
+    #   end
     def array(
       name,
       as: nil,
@@ -1320,6 +1433,22 @@ module Apiwork
     #   array? :labels do
     #     string
     #   end
+    #
+    # @example Optional array of discriminated union
+    #   array? :items do
+    #     union discriminator: :type do
+    #       variant tag: 'text' do
+    #         object do
+    #           string :content
+    #         end
+    #       end
+    #       variant tag: 'image' do
+    #         object do
+    #           string :url
+    #         end
+    #       end
+    #     end
+    #   end
     def array?(
       name,
       as: nil,
@@ -1346,6 +1475,113 @@ module Apiwork
       )
     end
 
+    # @api public
+    # Defines a record.
+    #
+    # @param name [Symbol]
+    #   The name.
+    # @param as [Symbol, nil] (nil)
+    #   The target attribute name.
+    # @param default [Object, nil] (nil)
+    #   The default value.
+    # @param deprecated [Boolean] (false)
+    #   Whether deprecated. Metadata included in exports.
+    # @param description [String, nil] (nil)
+    #   The description. Metadata included in exports.
+    # @param nullable [Boolean] (false)
+    #   Whether the value can be `null`.
+    # @param optional [Boolean] (false)
+    #   Whether the param is optional.
+    # @param required [Boolean] (false)
+    #   Whether the param is required.
+    # @yield block defining value type
+    # @return [void]
+    #
+    # @example Record of integers
+    #   record :scores do
+    #     integer
+    #   end
+    #
+    # @example Record of objects
+    #   record :settings do
+    #     object do
+    #       string :value
+    #       boolean :enabled
+    #     end
+    #   end
+    def record(
+      name,
+      as: nil,
+      default: nil,
+      deprecated: false,
+      description: nil,
+      nullable: false,
+      optional: false,
+      required: false,
+      &block
+    )
+      param(
+        name,
+        as:,
+        default:,
+        deprecated:,
+        description:,
+        nullable:,
+        optional:,
+        required:,
+        type: :record,
+        &block
+      )
+    end
+
+    # @api public
+    # Defines an optional record.
+    #
+    # @param name [Symbol]
+    #   The name.
+    # @param as [Symbol, nil] (nil)
+    #   The target attribute name.
+    # @param default [Object, nil] (nil)
+    #   The default value.
+    # @param deprecated [Boolean] (false)
+    #   Whether deprecated. Metadata included in exports.
+    # @param description [String, nil] (nil)
+    #   The description. Metadata included in exports.
+    # @param nullable [Boolean] (false)
+    #   Whether the value can be `null`.
+    # @param required [Boolean] (false)
+    #   Whether the param is required.
+    # @yield block defining value type
+    # @return [void]
+    #
+    # @example Optional record
+    #   record? :metadata do
+    #     string
+    #   end
+    def record?(
+      name,
+      as: nil,
+      default: nil,
+      deprecated: false,
+      description: nil,
+      nullable: false,
+      required: false,
+      &block
+    )
+      param(
+        name,
+        as:,
+        default:,
+        deprecated:,
+        description:,
+        nullable:,
+        required:,
+        optional: true,
+        type: :record,
+        &block
+      )
+    end
+
     # @api public
     # Defines a union.
     #
@@ -1552,6 +1788,8 @@ module Apiwork
       optional: false,
       required: false
     )
+      reference_type = to || name
+
       param(
         name,
         as:,
@@ -1561,7 +1799,8 @@ module Apiwork
         nullable:,
         optional:,
         required:,
-        type: to || name,
+        custom_type: reference_type,
+        type: reference_type,
       )
     end
 
@@ -1598,6 +1837,8 @@ module Apiwork
       nullable: false,
       required: false
     )
+      reference_type = to || name
+
       param(
         name,
         as:,
@@ -1606,8 +1847,9 @@ module Apiwork
         description:,
         nullable:,
         required:,
+        custom_type: reference_type,
         optional: true,
-        type: to || name,
+        type: reference_type,
       )
     end
 

data/lib/apiwork/representation/attribute.rb

@@ -18,7 +18,7 @@ module Apiwork
         decimal: %i[float double],
         integer: %i[int32 int64],
         number: %i[float double],
-        string: %i[email uuid url date datetime ipv4 ipv6 password hostname],
+        string: %i[date datetime email hostname ipv4 ipv6 password text url uuid],
       }.freeze
 
       # @!attribute [r] description
@@ -117,7 +117,7 @@ module Apiwork
           element.validate!
           @element = element
           type = element.type
-          @of = element.inner&.type if element.type == :array
+          @of = element.inner&.type if [:array, :record].include?(element.type)
         end
 
         if owner_representation_class.model_class.present?

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
@@ -197,11 +198,11 @@ module Apiwork
         #   The example. Metadata included in exports.
         # @param filterable [Boolean] (false)
         #   Whether the attribute is filterable.
-        # @param format [Symbol, nil] (nil) [:date, :datetime, :double, :email, :float, :hostname, :int32, :int64, :ipv4, :ipv6, :password, :url, :uuid]
+        # @param format [Symbol, nil] (nil) [:date, :datetime, :double, :email, :float, :hostname, :int32, :int64, :ipv4, :ipv6, :password, :text, :url, :uuid]
         #   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`).
+        #   `:ipv4`, `:ipv6`, `:password`, `:text`, `:url`, `:uuid`).
         # @param max [Integer, nil] (nil)
         #   The maximum. For `:array`: size. For `:decimal`, `:integer`, `:number`: value. For `:string`: length.
         # @param min [Integer, nil] (nil)
@@ -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.3.1'
+  VERSION = '0.5.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apiwork
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0
 platform: ruby
 authors:
 - skiftle
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-04 00:00:00.000000000 Z
+date: 2026-03-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -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