smithy-schema 1.0.0.pre0 → 1.0.0.pre1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2dc2a4e23db98951101c73d858d031c3a1e2b757c49d891c448bd3e049a6917d
-  data.tar.gz: 888f46534f8c174d00f6a09470ce69ac183ab68dd9d9c43e55f9e4ec51b3cf07
+  metadata.gz: 7969227c178251f03785e6acea6cec078f3a5b58f266442dc3d980e6d4b91df5
+  data.tar.gz: 9308246739c8b7f192dce70a2dc7dcd7a26aa8446f8e0be1da54c724de30f4ec
 SHA512:
-  metadata.gz: 949146a02a4357e994ad85028d06cb198bb20dbb208c5d8d001762ff7653b7c9c03ca2f7aa313aa85f2b6051798184dc24b3c2547a9e034cab818c3bb6b0edef
-  data.tar.gz: f63565e8f4297c5c9e20720d89ac5f316f8ac590572f4d600196d2aa15cc82c9720496c26559a300806d1346bb1cd611ee00f7caa06047c96b60b8add5a8676c
+  metadata.gz: 8098ac1b23fade8569d4e5bf57f645ec5cf7d2783740327dcad4564b19b6f86e442a5d7b8af092170e581ca2948f6ba4ca47d2e9874b58ba333d08a9826a52cb
+  data.tar.gz: '03649f8030eea28a80d0a7f37d306f6ca33933437e56c7acb4a579f9ea4423d3b0c01d819c685096392792031e1a6630e09b0085351baf18dea748203dda37ad'

data/CHANGELOG.md

@@ -1,2 +1,4 @@
 Unreleased Changes
 ------------------
+
+* Feature - Initial version of this gem.

data/VERSION

@@ -1 +1 @@
-1.0.0.pre0
+1.0.0.pre1

data/lib/smithy-schema/document.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require_relative 'document_utils/deserializer'
+require_relative 'document_utils/serializer'
+require 'delegate'
+
+module Smithy
+  module Schema
+    # A Smithy document, representing typed or untyped data from the Smithy data model.
+    # The Document class delegates to the underlying data object while providing additional
+    # document-specific functionality. The document will represent protocol-agnostic
+    # data structures in the Smithy data model.
+    #
+    # This class includes capabilities for:
+    #
+    # - Serialization and deserialization of document data
+    # - Type-aware data handling
+    # - Support for JSON document format
+    #
+    # To create a Document using various input formats, use {Document.create}
+    # @example Basic usage with a document
+    #   document = Document.new(name: "document")
+    #   document  # => { "name" => "document" }
+    class Document < ::SimpleDelegator
+      # A Smithy document, representing typed or untyped data from the Smithy data model.
+      # This class delegates to the underlying data object while providing additional
+      # document-specific functionality.
+      # @param [Object] data document data
+      # @param [Hash] options
+      # @option options [String] :discriminator This value is used to identify a specific
+      #  shape. This is equivalent of a Smithy shape ID.
+      def initialize(data, options = {})
+        @data = data
+        @discriminator = options[:discriminator]
+        super(@data)
+      end
+
+      # Returns the discriminator value for the document.
+      #
+      # @return [String, nil] discriminator
+      attr_reader :discriminator
+
+      # Serializes a {Document} with optional formatting.
+      #
+      # @param [TypeRegistry] type_registry Registry is required for identifying
+      #  and validating typed documents
+      # @param [Hash] opts Formatting options
+      # @option opts [Boolean] :timestamp_format Whether to use the `timestampFormat`
+      #  trait or ignore it. The `timestampFormat` trait is ignored by default.
+      # @option opts [Boolean] :json_name Whether to use `jsonName` trait
+      #   or just member name. The `jsonName` trait is ignored by default.
+      def serialize(type_registry, opts = {})
+        validate_document(type_registry)
+
+        opts[:type_registry] = type_registry
+        opts[:json] = true
+        serializer = DocumentUtils::Serializer.new(opts)
+        serializer.format_document_data(type_registry[@discriminator], @data)
+      end
+
+      # Deserializes a {Document} into a type.
+      #
+      # @param [TypeRegistry, nil] type_registry Registry is required for
+      #  identifying and deserializing typed documents. Either this or shape
+      #  must be provided.
+      # @param [StructureShape, nil] shape shape to use for deserialization.
+      #  If provided, this shape takes precedence over the document's discriminator.
+      #  The shape must have a type.
+      def deserialize(type_registry: nil, shape: nil)
+        msg = 'either a type registry or a structure shape must be provided to deserialize'
+        raise ArgumentError, msg unless type_registry || shape
+
+        type_registry.nil? ? validate_shape(shape) : validate_document(type_registry)
+
+        shape ||= type_registry[@discriminator]
+        deserializer = DocumentUtils::Deserializer.new(type_registry: type_registry)
+        deserializer.deserialize(@data, shape, shape.type.new)
+      end
+
+      private
+
+      def validate_document(type_registry)
+        msg = 'unable validate typed document - must have a discriminator'
+        raise ArgumentError, msg unless @discriminator
+
+        msg = 'document discriminator not found in type registry'
+        raise ArgumentError, msg unless type_registry.key?(@discriminator)
+      end
+
+      def validate_shape(shape)
+        msg = 'invalid shape - must be a structure shape with type'
+        raise ArgumentError, msg unless shape.is_a?(Shapes::StructureShape) && shape.type
+      end
+
+      class << self
+        # Create a {Document} from various input formats.
+        #
+        # @param [Object] data Input data could be one of the following: a Ruby object,
+        #  a Struct type, or a parsed JSON with type discriminator key.
+        # @param [TypeRegistry, nil] type_registry Type Registry is required for
+        #  identifying and serializing typed documents. Option for untyped documents.
+        # @return [Document] document
+        #
+        # @example Ruby Object as input
+        #   # creating an untyped document
+        #   document = Smithy::Schema::Document.create(foo: "bar")
+        #   # => {"foo" => "bar"}
+        # @example Structure type as input
+        #   structure = some_structure.type.new(some_data)
+        #   # => #<struct SampleService::Types::Structure ...>
+        #
+        #   # Type Registry is required to properly serialize
+        #   document = Smithy::Schema::Document.create(structure, type_registry)
+        #   # => #<Smithy::Schema::Document ...>
+        # @example JSON data
+        #   # given the following json data
+        #   parsed_json = {
+        #     "__type" => "smithy.ruby.tests#Structure",
+        #     "string" => "hello"
+        #   }
+        #
+        #   document = serializer.create(parsed_json, type_registry)
+        #   # => an instance of Smithy::Schema::Document
+        #   document.discriminator
+        #   # => "smithy.ruby.tests#Structure"
+        def create(data, type_registry = nil)
+          raise ArgumentError, 'invalid data - document cannot be nil' if data.nil?
+
+          return untyped_document(data) if type_registry.nil?
+
+          validate_typed_data(data, type_registry)
+          typed_document(data, type_registry)
+        end
+
+        private
+
+        def discriminator?(data)
+          data.is_a?(Hash) && data.key?('__type')
+        end
+
+        def untyped_document(data)
+          serializer = DocumentUtils::Serializer.new
+          new(serializer.serialize_untyped(data))
+        end
+
+        def typed_document(data, type_registry)
+          opts = { type_registry: type_registry }
+          case data
+          when Structure
+            shape = type_registry.shape_by_type(data.class)
+          else
+            opts = opts.merge(json: true, json_name: true)
+            shape = type_registry[data['__type']]
+          end
+          serializer = DocumentUtils::Serializer.new(opts)
+          new(serializer.format_document_data(shape, data), discriminator: shape.id)
+        end
+
+        def validate_typed_data(data, type_registry)
+          case data
+          when Structure
+            msg = 'given type class not found in type registry'
+            raise ArgumentError, msg unless type_registry.shape_by_type?(data.class)
+          else
+            msg = 'document discriminator not found in type registry'
+            raise ArgumentError, msg if discriminator?(data) && !type_registry.key?(data['__type'])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/smithy-schema/document_utils/deserializer.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Schema
+    module DocumentUtils
+      # Deserializes document data into a type.
+      # @api private
+      class Deserializer
+        include Shapes
+
+        def initialize(options = {})
+          @type_registry = options[:type_registry]
+        end
+
+        def deserialize(data, shape, target)
+          ref = shape.is_a?(ShapeRef) ? shape : ShapeRef.new(shape: shape)
+          shape(ref, data, target)
+        end
+
+        private
+
+        def shape(ref, value, target = nil) # rubocop:disable Metrics/CyclomaticComplexity
+          case ref.shape
+          when BlobShape then Base64.strict_decode64(value)
+          when DocumentShape then document(value)
+          when FloatShape then float(value)
+          when ListShape then list(ref, value, target)
+          when MapShape then map(ref, value, target)
+          when StructureShape then structure(ref, value, target)
+          when TimestampShape then timestamp(value)
+          when UnionShape then union(ref, value, target)
+          else value
+          end
+        end
+
+        def document(values)
+          return values unless values.is_a?(Hash) && values.key?('__type')
+
+          msg = 'invalid document - document discriminator not found in type registry'
+          raise ArgumentError, msg unless @type_registry.key?(values['__type'])
+
+          shape(ShapeRef.new(shape: @type_registry[values['__type']]), values)
+        end
+
+        def float(value)
+          case value
+          when 'Infinity' then ::Float::INFINITY
+          when '-Infinity' then -::Float::INFINITY
+          when 'NaN' then ::Float::NAN
+          when nil then nil
+          else value.to_f
+          end
+        end
+
+        def list(ref, values, target = nil)
+          return if values.nil?
+
+          target = [] if target.nil?
+          values.each do |value|
+            target << shape(ref.shape.member, value) unless value.nil?
+          end
+          target
+        end
+
+        def map(ref, values, target = nil)
+          return if values.nil?
+
+          target = {} if target.nil?
+          values.each do |key, value|
+            target[key] = shape(ref.shape.value, value) unless value.nil?
+          end
+          target
+        end
+
+        def structure(ref, values, target = nil)
+          return if values.nil?
+
+          target = ref.shape.type.new if target.nil?
+          ref.shape.members.each do |member_name, member_ref|
+            value = values[location_name(member_ref)]
+            target[member_name] = shape(member_ref, value) unless value.nil?
+          end
+          target
+        end
+
+        def timestamp(value)
+          case value
+          when nil then nil
+          when Numeric
+            Time.at(value).utc
+          when /^[\d.]+$/
+            Time.at(value.to_f).utc
+          else
+            begin
+              fractional_time = Time.parse(value).to_f
+              Time.at(fractional_time).utc
+            rescue ArgumentError
+              raise "unhandled timestamp format `#{value}'"
+            end
+          end
+        end
+
+        def union(ref, values, target = nil) # rubocop:disable Metrics/AbcSize
+          ref.shape.members.each do |member_name, member_ref|
+            value = values[location_name(member_ref)]
+            next if value.nil?
+
+            target = ref.shape.member_type(member_name) if target.nil?
+            return target.new(member_name => shape(member_ref, value))
+          end
+
+          values.delete('__type')
+          key, value = values.first
+          ref.shape.member_type(:unknown).new(key, value)
+        end
+
+        def location_name(ref)
+          return ref.member_name unless @json_name
+
+          ref.traits['smithy.api#jsonName'] || ref.member_name
+        end
+      end
+    end
+  end
+end

data/lib/smithy-schema/document_utils/serializer.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'time'
+
+module Smithy
+  module Schema
+    module DocumentUtils
+      # Serializes data into a document data.
+      # @api private
+      class Serializer
+        include Shapes
+
+        def initialize(options = {})
+          @type_registry = options[:type_registry]
+          @json = options[:json] || false
+          @json_name = options[:json_name] || false
+          @timestamp_format = options[:timestamp_format] || false
+        end
+
+        def format_document_data(shape, data)
+          ref = shape.is_a?(ShapeRef) ? shape : ShapeRef.new(shape: shape)
+          document_data = shape(ref, data)
+          document_data['__type'] = shape.id
+          document_data
+        end
+
+        def serialize_untyped(values)
+          return if values.nil?
+
+          case values
+          when Time then values.utc.to_i # timestamp format is "epoch-seconds" by default
+          when Hash
+            values.each_with_object({}) do |(k, v), h|
+              h[k.to_s] = serialize_untyped(v)
+            end
+          when Array then values.map { |d| serialize_untyped(d) }
+          else values
+          end
+        end
+
+        private
+
+        def shape(ref, values) # rubocop:disable Metrics/CyclomaticComplexity
+          case ref.shape
+          when BlobShape then blob(values)
+          when DocumentShape then document(values)
+          when FloatShape then float(values)
+          when ListShape then list(ref, values)
+          when MapShape then map(ref, values)
+          when StructureShape then structure(ref, values)
+          when TimestampShape then timestamp(ref, values)
+          when UnionShape then union(ref, values)
+          else values
+          end
+        end
+
+        def blob(value)
+          return value if @json # blob is already encoded
+
+          Base64.strict_encode64(value.respond_to?(:read) ? value.read : value)
+        end
+
+        def document(values)
+          shape = document_shape(values)
+          return values unless shape
+
+          format_document_data(shape, values)
+        end
+
+        def document_shape(values)
+          case values
+          when Structure
+            @type_registry.shape_by_type(values.class)
+          when Hash
+            @type_registry[values['__type']]
+          end
+        end
+
+        def float(value)
+          if value == ::Float::INFINITY
+            'Infinity'
+          elsif value == -::Float::INFINITY
+            '-Infinity'
+          elsif value.to_f.nan?
+            'NaN'
+          else
+            value.to_f
+          end
+        end
+
+        def list(ref, values)
+          return if values.nil?
+
+          shape = ref.shape
+          values.collect do |value|
+            shape(shape.member, value)
+          end
+        end
+
+        def map(ref, values)
+          return if values.nil?
+
+          shape = ref.shape
+          values.each.with_object({}) do |(key, value), data|
+            data[key.to_s] = shape(shape.value, value)
+          end
+        end
+
+        def structure(ref, values)
+          return if values.nil?
+
+          ref.shape.members.each_with_object({}) do |(member_name, member_ref), data|
+            value = resolve_value(member_name, member_ref, values.to_h)
+            data[location_name(member_ref)] = shape(member_ref, value) unless value.nil?
+          end
+        end
+
+        def timestamp(ref, value)
+          value = normalize_timestamp_value(value)
+          return value.to_i unless @timestamp_format
+
+          trait = 'smithy.api#timestampFormat'
+          case ref.traits[trait] || ref.shape.traits[trait]
+          when 'date-time' then value.utc.iso8601
+          when 'http-date' then value.utc.httpdate
+          else
+            # default to epoch-seconds
+            value.to_i
+          end
+        end
+
+        def union(ref, values)
+          return if values.nil?
+
+          data = {}
+          if values.is_a?(Union)
+            _name, member_ref = ref.shape.member_by_type(values.class)
+            data[location_name(member_ref)] = shape(member_ref, values)
+          else
+            key, value = values.first
+            if (member_ref = resolve_member_ref(ref, key))
+              data[location_name(member_ref)] = shape(member_ref, value)
+            end
+          end
+          data
+        end
+
+        def location_name(ref)
+          return ref.member_name unless @json_name
+
+          ref.traits['smithy.api#jsonName'] || ref.member_name
+        end
+
+        def normalize_timestamp_value(value)
+          case value
+          when Time then value
+          when Numeric then Time.at(value)
+          else Time.parse(value)
+          end
+        end
+
+        def resolve_member_ref(ref, name)
+          return ref.shape.member(name) if ref.shape.member?(name)
+
+          ref.shape.members.values.find do |member_ref|
+            member_ref.traits['smithy.api#jsonName'] == name || member_ref.member_name == name
+          end
+        end
+
+        def resolve_value(member_name, member_ref, values)
+          if (json_name = member_ref.traits['smithy.api#jsonName'])
+            value = values[json_name]
+            return value unless value.nil?
+          end
+          values[member_name] || values[member_ref.member_name]
+        end
+      end
+    end
+  end
+end

data/lib/smithy-schema/empty_structure.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Schema
+    # An empty Struct that includes the {Schema::Structure} module.
+    class EmptyStructure < Struct.new(nil) # rubocop:disable Style/StructInheritance
+      include Smithy::Schema::Structure
+    end
+  end
+end

data/lib/smithy-schema/shapes.rb

@@ -9,6 +9,7 @@ module Smithy
         def initialize(options = {})
           @id = options[:id]
           @traits = options[:traits] || {}
+          @metadata = {}
         end
 
         # @return [String, nil] Absolute shape ID from model
@@ -16,53 +17,46 @@ module Smithy
 
         # @return [Hash<String, Object>]
         attr_accessor :traits
-      end
 
-      # Represents an aggregate shape that has members.
-      class Structure < Shape
-        def initialize(options = {})
-          super
-          @members = {}
-          @names_by_member_name = {}
+        # @return [Object]
+        def [](key)
+          @metadata[key]
         end
 
-        # @return [Hash<Symbol, MemberShape>]
-        attr_accessor :members
-
-        # @return [Hash<String, Symbol>]
-        attr_accessor :names_by_member_name
-
-        # @return [Class, nil]
-        attr_accessor :type
-
-        # @return [MemberShape]
-        def add_member(name, member_name, shape, traits: {})
-          @names_by_member_name[member_name] = name
-          @members[name] = MemberShape.new(member_name, shape, traits: traits)
+        # @param [Symbol] key
+        # @param [Object] value
+        def []=(key, value)
+          @metadata[key] = value
         end
+      end
 
-        # @param [Symbol] name
-        # @return [Boolean]
-        def member?(name)
-          @members.key?(name)
+      # A reference to a shape.
+      class ShapeRef
+        def initialize(options = {})
+          @shape = options[:shape]
+          @member_name = options[:member_name]
+          @traits = options[:traits] || {}
+          @metadata = {}
         end
 
-        # @param [Symbol] name
-        # @return [MemberShape, nil]
-        def member(name)
-          @members[name]
-        end
+        # @return [Shape]
+        attr_reader :shape
 
-        # @param [String] member_name
-        # @return [Boolean]
-        def name_by_member_name?(member_name)
-          @names_by_member_name.key?(member_name)
+        # @return [String, nil]
+        attr_reader :member_name
+
+        # @return [Hash<String, Object>]
+        attr_reader :traits
+
+        # @return [Object]
+        def [](key)
+          @metadata[key]
         end
 
-        # @param [String] member_name
-        # @return [Symbol, nil]
-        def name_by_member_name(member_name)
-          @names_by_member_name[member_name]
+        # @param [Symbol] key
+        # @param [Object] value
+        def []=(key, value)
+          @metadata[key] = value
         end
       end
 
@@ -78,7 +72,7 @@ module Smithy
           yield self if block_given?
         end
 
-        # @return [String, nil] Service name
+        # @return [String]
         attr_accessor :name
 
         # @return [String, nil]
@@ -122,16 +116,16 @@ module Smithy
           yield self if block_given?
         end
 
-        # @return [String, nil] Operation name
+        # @return [String]
         attr_accessor :name
 
-        # @return [StructureShape, nil]
+        # @return [ShapeRef]
         attr_accessor :input
 
-        # @return [StructureShape, nil]
+        # @return [ShapeRef]
         attr_accessor :output
 
-        # @return [Array<StructureShape>]
+        # @return [Array<ShapeRef>]
         attr_accessor :errors
       end
 
@@ -148,87 +142,157 @@ module Smithy
       class DocumentShape < Shape; end
 
       # Represents an Enum shape.
-      class EnumShape < Structure; end
+      class EnumShape < Shape
+        def initialize(options = {})
+          super
+          @members = {}
+        end
+
+        # @return [Hash<Symbol, ShapeRef>]
+        attr_accessor :members
+
+        # @return [ShapeRef]
+        def add_member(name, shape_ref)
+          @members[name] = shape_ref
+        end
+
+        # @param [Symbol] name
+        # @return [Boolean]
+        def member?(name)
+          @members.key?(name)
+        end
+
+        # @param [Symbol] name
+        # @return [ShapeRef, nil]
+        def member(name)
+          @members[name]
+        end
+      end
 
       # Represents the following shapes: Byte, Short, Integer, Long, BigInteger.
       class IntegerShape < Shape; end
 
       # Represents an IntEnum shape.
-      class IntEnumShape < Structure; end
+      class IntEnumShape < Shape
+        def initialize(options = {})
+          super
+          @members = {}
+        end
+
+        # @return [Hash<Symbol, ShapeRef>]
+        attr_accessor :members
+
+        # @return [ShapeRef]
+        def add_member(name, shape_ref)
+          @members[name] = shape_ref
+        end
+
+        # @param [Symbol] name
+        # @return [Boolean]
+        def member?(name)
+          @members.key?(name)
+        end
+
+        # @param [Symbol] name
+        # @return [ShapeRef, nil]
+        def member(name)
+          @members[name]
+        end
+      end
 
       # Represents both Float and Double shapes.
       class FloatShape < Shape; end
 
       # Represents a List shape.
       class ListShape < Shape
-        def initialize(options = {})
-          super
-          @member = nil
-        end
-
-        # @return [MemberShape, nil]
+        # @return [ShapeRef]
         attr_accessor :member
-
-        def set_member(shape, traits: {})
-          @member = MemberShape.new('member', shape, traits: traits)
-        end
       end
 
       # Represents a Map shape.
       class MapShape < Shape
+        # @return [ShapeRef]
+        attr_accessor :key
+
+        # @return [ShapeRef]
+        attr_accessor :value
+      end
+
+      # Represents a String shape.
+      class StringShape < Shape; end
+
+      # Represents a Structure shape.
+      class StructureShape < Shape
         def initialize(options = {})
           super
-          @key = nil
-          @value = nil
+          @members = {}
         end
 
-        # @return [MemberShape, nil]
-        attr_accessor :key
+        # @return [Hash<Symbol, ShapeRef>]
+        attr_accessor :members
 
-        # @return [MemberShape, nil]
-        attr_accessor :value
+        # @return [Class]
+        attr_accessor :type
 
-        def set_key(shape, traits: {})
-          @key = MemberShape.new('key', shape, traits: traits)
+        # @return [ShapeRef]
+        def add_member(name, shape_ref)
+          @members[name] = shape_ref
         end
 
-        def set_value(shape, traits: {})
-          @value = MemberShape.new('value', shape, traits: traits)
+        # @param [Symbol] name
+        # @return [Boolean]
+        def member?(name)
+          @members.key?(name)
         end
-      end
-
-      # Represents a String shape.
-      class StringShape < Shape; end
 
-      # Represents a Structure shape.
-      class StructureShape < Structure
+        # @param [Symbol] name
+        # @return [ShapeRef, nil]
+        def member(name)
+          @members[name]
+        end
       end
 
       # Represents a Timestamp shape.
       class TimestampShape < Shape; end
 
       # Represents both Union and EventStream shapes.
-      class UnionShape < Structure
+      class UnionShape < Shape
         def initialize(options = {})
           super
+          @members = {}
           @member_types = {}
           @members_by_type = {}
         end
 
+        # @return [Hash<Symbol, ShapeRef>]
+        attr_accessor :members
+
         # @return [Hash<Symbol, Class>]
-        attr_accessor :member_types
+        attr_reader :member_types
+
+        # @return [Hash<Class, [String, ShapeRef]>]
+        attr_reader :members_by_type
 
-        # @return [Hash<Class, MemberShape>]
-        attr_accessor :members_by_type
+        # @return [Class]
+        attr_accessor :type
 
-        # @return [MemberShape]
-        def add_member(name, member_name, shape, type, traits: {})
-          member = MemberShape.new(member_name, shape, traits: traits)
-          @members[name] = member
-          @names_by_member_name[member_name] = name
+        # @return [ShapeRef]
+        def add_member(name, type, shape_ref)
           @member_types[name] = type
-          @members_by_type[type] = member
-          member
+          @members_by_type[type] = [name, shape_ref]
+          @members[name] = shape_ref
+        end
+
+        # @param [Symbol] name
+        # @return [Boolean]
+        def member?(name)
+          @members.key?(name)
+        end
+
+        # @param [Symbol] name
+        # @return [ShapeRef, nil]
+        def member(name)
+          @members[name]
         end
 
         # @param [Symbol] name
@@ -250,30 +314,12 @@ module Smithy
         end
 
         # @param [Class] type
-        # @return [MemberShape, nil]
+        # @return [ShapeRef, nil]
         def member_by_type(type)
           @members_by_type[type]
         end
       end
 
-      # Represents a member shape.
-      class MemberShape
-        def initialize(name, shape, traits: {})
-          @name = name
-          @shape = shape
-          @traits = traits
-        end
-
-        # @return [String] Member name
-        attr_accessor :name
-
-        # @return [Shape] Referenced shape
-        attr_accessor :shape
-
-        # @return [Hash<String, Object>]
-        attr_accessor :traits
-      end
-
       # Prelude shape definitions.
       module Prelude
         BigDecimal = BigDecimalShape.new(id: 'smithy.api#BigDecimal')
@@ -321,6 +367,7 @@ module Smithy
           id: 'smithy.api#Unit',
           traits: { 'smithy.api#unitType' => {} }
         )
+        Unit.type = Schema::EmptyStructure
       end
     end
   end

data/lib/smithy-schema/structure.rb

@@ -2,15 +2,13 @@
 
 module Smithy
   module Schema
-    # A module mixed into Structs that provides utility methods.
+    # A module mixed into Structs that provides utility methods for Structure shapes.
     module Structure
       # Deeply converts the Struct into a hash. Structure members that
       # are `nil` are omitted from the resultant hash.
       # @return [Hash, Structure]
       def to_h(obj = self)
         case obj
-        when Union
-          obj.to_h
         when Structure
           _to_h_structure(obj)
         when Hash
@@ -42,10 +40,5 @@ module Smithy
         obj.collect { |value| to_hash(value) }
       end
     end
-
-    # An empty Struct that includes the {Client::Structure} module.
-    EmptyStructure = Struct.new do
-      include Smithy::Schema::Structure
-    end
   end
 end

data/lib/smithy-schema/type_registry.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Schema
+    # A registry that contains a map of Smithy shape ID to its shape defined in a schema.
+    # The registered shapes are limited to {Shapes::StructureShape} with a type.
+    #
+    # This registry has the following functionalities:
+    #
+    # * Access shape by shape ID
+    # * Access shape by its type
+    # * Register shape to the Registry
+    # * Supports enumeration of registered shapes
+    #
+    # You could also combine multiple registries into one {TypeRegistry}.
+    #
+    # @example Creating a new Registry
+    #  # accepts an array of structure shapes
+    #  registry = TypeRegistry.new(StructureShape1, StructureShape2)
+    #
+    # @example Shape Lookup
+    #  # Find shape by its id
+    #  registry["someId"]
+    #  # => #<Smithy::Schema::Shapes::StructureShape...>
+    #
+    #  # Find shape by its type
+    #  registry.shape_by_type(ExampleService::Types::Structure)
+    #  # => #<Smithy::Schema::Shapes::StructureShape...>
+    #
+    # @example Combining multiple registries
+    #  registry.concat(registry1, registry2)
+    #  # => #<Smithy::Schema::TypeRegistry...>
+    class TypeRegistry
+      include Enumerable
+
+      # @param [Array<Shapes::StructureShape>] shapes
+      def initialize(shapes = [])
+        @registry = {}
+        @shapes_by_type = {}
+        shapes.each do |shape|
+          self[shape.id] = shape
+        end
+      end
+
+      def each(&)
+        @registry.each(&)
+      end
+
+      # @param [String] id
+      # @return [Shapes::StructureShape, nil]
+      def [](id)
+        @registry[id]
+      end
+
+      # @param [String] id
+      # @param [Shapes::StructureShape] shape
+      def []=(id, shape)
+        validate_shape(shape)
+        @registry[id] = shape
+        @shapes_by_type[shape.type] = shape
+      end
+
+      # @return [Boolean]
+      def empty?
+        @registry.empty?
+      end
+
+      # @param [String] id
+      def key?(id)
+        @registry.key?(id)
+      end
+      alias include? key?
+
+      # @return [Array<String>]
+      def keys
+        @registry.keys
+      end
+
+      # @param [Class] type
+      def shape_by_type?(type)
+        @shapes_by_type.key?(type)
+      end
+
+      # @param [Class] type
+      # @return [Shapes::StructureShape, nil]
+      def shape_by_type(type)
+        @shapes_by_type[type]
+      end
+
+      # @return [Array<Shape::StructureShape>]
+      def values
+        @registry.values
+      end
+
+      # Merges multiple type registries into a new registry.
+      #
+      # @param [Array<TypeRegistry>] type_registries
+      # @return [TypeRegistry]
+      def merge(*type_registries)
+        registry = TypeRegistry.new
+        @registry.each do |shape_id, shape|
+          registry[shape_id] = shape
+        end
+        type_registries.each do |type_registry|
+          unless type_registry.is_a?(TypeRegistry)
+            raise ArgumentError, "expected TypeRegistry, got #{type_registry.class}"
+          end
+
+          type_registry.each do |shape_id, shape|
+            registry[shape_id] = shape
+          end
+        end
+        registry
+      end
+
+      private
+
+      def validate_shape(shape)
+        return if shape.is_a?(Shapes::StructureShape) && shape.type
+
+        raise ArgumentError, "expected a StructureShape with a type, got: #{shape.class}"
+      end
+    end
+  end
+end

data/lib/smithy-schema/union.rb

@@ -4,16 +4,16 @@ require 'delegate'
 
 module Smithy
   module Schema
-    # Top level class for all generated Union types
-    class Union < ::SimpleDelegator
+    # A module mixed into Structs that provides utility methods for Union shapes.
+    module Union
       include Structure
 
-      def to_s
-        "#<#{self.class.name} #{__getobj__ || 'nil'}>"
+      def member
+        members.find { |m| !self[m].nil? }
       end
 
       def value
-        __getobj__
+        self[member] if member
       end
     end
   end

data/lib/smithy-schema.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
-require_relative 'smithy-schema/shapes'
 require_relative 'smithy-schema/structure'
+require_relative 'smithy-schema/empty_structure'
 require_relative 'smithy-schema/union'
 
+require_relative 'smithy-schema/shapes'
+require_relative 'smithy-schema/document'
+require_relative 'smithy-schema/type_registry'
+
 module Smithy
-  # Base module for Smithy model classes.
-  module Model
+  # Base module for Smithy schema classes.
+  module Schema
     VERSION = File.read(File.expand_path('../VERSION', __dir__.to_s)).strip
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: smithy-schema
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre0
+  version: 1.0.0.pre1
 platform: ruby
 authors:
 - Amazon Web Services
 bindir: bin
 cert_chain: []
-date: 2025-03-06 00:00:00.000000000 Z
+date: 2025-06-26 00:00:00.000000000 Z
 dependencies: []
 description: Smithy is a code generation toolkit for creating Client and Server SDKs
   from Smithy models.
@@ -18,8 +18,13 @@ files:
 - CHANGELOG.md
 - VERSION
 - lib/smithy-schema.rb
+- lib/smithy-schema/document.rb
+- lib/smithy-schema/document_utils/deserializer.rb
+- lib/smithy-schema/document_utils/serializer.rb
+- lib/smithy-schema/empty_structure.rb
 - lib/smithy-schema/shapes.rb
 - lib/smithy-schema/structure.rb
+- lib/smithy-schema/type_registry.rb
 - lib/smithy-schema/union.rb
 homepage: https://github.com/smithy-lang/smithy-ruby
 licenses: