lutaml-model 0.8.123 → 0.8.125

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d77a19ece999a4de97c03776b3f56bc31eb217fb14904362eef4c98b4623be6
-  data.tar.gz: b76ef3e5de721b3e94a02dbac605c61fe3ca44fe97388b8fca1ec4645c3ab494
+  metadata.gz: bd52cd1acd33af2b1f8abe39a9d57c4412618d63ee65b516204ef4fa9f7ff047
+  data.tar.gz: 903e6d8ed42b95b0c5f79616f362d856b79ef54c90b3bbc1ba854c3345e79bd2
 SHA512:
-  metadata.gz: 3a03373b96d83e69500cbd2371557f5ced955e85964b3a92340e8bf3cb4da0b45ea3f83ed59fc6f47e410661c5a2e0ca0b9a5d2db6d890ce9d192ed35ccda2c1
-  data.tar.gz: 6675bdd426008a94d3e1367b584d3ce92e242b6d6e6e3a85c1e7afc544ab57cce7da847a7af53c9a3f11bd1bfb4f3b49cefb1032eb8157a5e2ddee32b4761545
+  metadata.gz: 125f630b5d0816ad0dbbf98e1650f9a221a19c83793fe05c38e384fa884ec251774e97b0ce9636be1a014f84f678fc2c4d42d9cbea108fc615051fbd1bf4112c
+  data.tar.gz: 9eec80327bca08b7cc3bb649c77c1b956356baa190d434ae86c5eebacaacfda95c5e2ed2392d6c1d2db7a98fa4a7e32d6d416eb74185d5f0ba8ba416cef66d2a

data/lib/compat/opal/lutaml_model_boot.rb

@@ -59,6 +59,7 @@ require "lutaml/model/context_registry"
 require "lutaml/model/deep_dupable"
 require "lutaml/model/error"
 require "lutaml/model/errors"
+require "lutaml/model/evolution_steps"
 require "lutaml/model/finalization_cache"
 require "lutaml/model/format_registry"
 require "lutaml/model/global_context"
@@ -283,6 +284,7 @@ require "lutaml/model/error/unknown_discriminator_error"
 require "lutaml/model/error/unknown_sequence_mapping_error"
 require "lutaml/model/error/unknown_type_error"
 require "lutaml/model/error/unresolvable_type_error"
+require "lutaml/model/error/unsupported_version_error"
 require "lutaml/model/error/validation_error"
 require "lutaml/model/error/validation_failed_error"
 require "lutaml/model/liquid/indexed_access"

data/lib/lutaml/key_value/transform.rb

@@ -165,14 +165,15 @@ module Lutaml
                          Concurrent::Map.new
                        end
 
-      # [model class, register, format, rule, generation] -> KvRulePlan,
-      # or false for ineligible rules. Class-level: the interpretive
-      # walk re-derived the same eligibility chain for the same rule at
-      # every node (~12 predicate allocations x nodes per heroku.json
-      # parse). Same idempotent-write, generation-retirement pattern as
-      # KV_GROUP_PLANS; false (not nil) marks ineligible so a miss never
-      # rebuilds.
-      KV_RULE_PLANS = if Lutaml::Model.opal?
+      # [model class, register, format, generation] -> { rule => plan }.
+      # Class-level, generation-retired: the whole dispatch table for a
+      # model mapping compiles once — kind (scalar/custom/hash_map/
+      # interpretive/skip/invalid), target attribute and validity — so
+      # process_mapping_rule stops re-probing rule predicates at every
+      # node (~12 predicate calls plus a key array per rule per node;
+      # 154k+154k allocations per heroku.json parse). Same
+      # idempotent-write pattern as KV_GROUP_PLANS.
+      KV_WALK_PLANS = if Lutaml::Model.opal?
                         {}
                       else
                         Lutaml::Model::RuntimeCompatibility
@@ -717,18 +718,20 @@ format)
 
       def process_mapping_rule(doc, instance, format, rule, options = {},
 partition = nil)
-        attr = attribute_for_rule(rule)
-        return if attr&.derived?
+        plans = walk_plans_for(format)
+        plan = plans[rule] ||= build_walk_plan(format, rule)
+        kind = plan.kind
+        return if kind == :skip
 
-        raise "Attribute '#{rule.to}' not found in #{self}" unless valid_rule?(
-          rule, attr
-        )
+        raise "Attribute '#{rule.to}' not found in #{self}" unless plan.valid
+
+        attr = plan.attr
 
         # lutaml-model#88: discriminator rules (and plain rules on a
         # partitioned key) must filter the raw value, so they keep the
         # interpretive path.
         partitioned = partition && kv_partition_group(rule, partition)
-        if partitioned.nil? && (plan = kv_rule_plan(format, rule, attr)) &&
+        if partitioned.nil? && kind == :scalar &&
             (value = kv_fast_extract(doc, plan))
           rule.deserialize(instance, kv_fast_cast(value, plan, instance),
                            attributes, self, options[:context], pre_cast: true)
@@ -742,20 +745,28 @@ partition = nil)
         end
         value = apply_value_map(value, rule.value_map(:from, options), attr)
 
-        if rule.has_custom_method_for_deserialization?
-          # An empty value ("", [], {}) is a present value per the
-          # missing-values semantics and must reach the custom method;
-          # only nil (non-existent) skips it (lutaml-model#746).
-          return if value.nil?
+        # An empty value ("", [], {}) is a present value per the
+        # missing-values semantics and must reach the custom method;
+        # only nil (non-existent) skips it (lutaml-model#746).
+        if (kind == :custom) && value.nil?
+          return
+        end
 
+        if kind == :custom
           return rule.deserialize(instance, value, attributes, model_class,
                                   options[:context])
         end
 
         value = rule.transform_value(attr, value, :from, format)
+        # Hash/child-mapping rules translate a hash document; an absent
+        # or explicit-null key has nothing to translate — the attribute
+        # keeps its uninitialized/default state (a nil here previously
+        # crashed translate_mappings).
+        return if value.nil? && kind == :hash_map
+
         value = translate_mappings(value, rule.hash_mappings, attr, format,
                                    instance)
-        unless rule.hash_mappings
+        unless kind == :hash_map
           value = cast_value(value, attr, format, rule,
                              instance)
         end
@@ -786,7 +797,8 @@ partition = nil)
       # Guard + cached target — an inline cache per rule. Complex rules
       # (custom methods, transforms, value maps, delegates, hash mappings,
       # unions, polymorphism) return nil and keep the interpretive path.
-      KvRulePlan = ::Struct.new(:wire, :klass, :collection)
+      WalkPlan = ::Struct.new(:kind, :attr, :valid, :wire, :klass,
+                              :collection)
 
       # Memoized (per transform) wire name for plain rules — the from
       # spelling never changes after definition.
@@ -808,15 +820,48 @@ partition = nil)
         @kv_serialize_plans[rule] ||= KvSerializePlan.new(rule_from_name(rule))
       end
 
-      def kv_rule_plan(format, rule, attr)
-        key = [model_class, lutaml_register, format, rule,
-               Lutaml::Model::GlobalContext.context_generation]
-        cached = KV_RULE_PLANS[key]
-        return cached == false ? nil : cached unless cached.nil?
+      def walk_plans_for(format)
+        generation = Lutaml::Model::GlobalContext.context_generation
+        if @lutaml_walk_plans.nil? || @lutaml_walk_generation != generation ||
+            @lutaml_walk_format != format
+          key = [model_class, lutaml_register, format, generation]
+          @lutaml_walk_plans =
+            (KV_WALK_PLANS[key] ||= build_walk_plans(format))
+          @lutaml_walk_generation = generation
+          @lutaml_walk_format = format
+        end
+        @lutaml_walk_plans
+      end
+
+      def build_walk_plans(format)
+        plans = {}.compare_by_identity
+        mappings_for(format).mappings(lutaml_register).each do |rule|
+          plans[rule] = build_walk_plan(format, rule)
+        end
+        plans
+      end
+
+      # The per-rule dispatch compile. Kind precedence mirrors the
+      # interpretive method exactly: skip (derived) > invalid >
+      # custom (deserialization custom method) > hash_map
+      # (hash_mappings truthy — translate, never cast) > scalar (the
+      # fast-extract eligibility) > interpretive.
+      def build_walk_plan(format, rule, _attrs = nil)
+        attr = attribute_for_rule(rule)
+        return WalkPlan.new(:skip, nil, false, nil, nil, false) if attr&.derived?
+
+        valid = valid_rule?(rule, attr)
+        kind =
+          if rule.has_custom_method_for_deserialization?
+            :custom
+          elsif rule.hash_mappings
+            :hash_map
+          else
+            plan = build_kv_rule_plan(format, rule, attr)
+            plan ? :scalar : :interpretive
+          end
 
-        plan = build_kv_rule_plan(format, rule, attr)
-        KV_RULE_PLANS[key] = plan || false
-        plan
+        plan || WalkPlan.new(kind, attr, valid, nil, nil, false)
       end
 
       # `rule.polymorphic` defaults to an empty Hash, which is truthy —
@@ -843,7 +888,8 @@ partition = nil)
           !attr.value_policy.whole_value?(type) &&
           !Lutaml::Model::Attribute.custom_from_probe?(type)
 
-        KvRulePlan.new(rule.name.to_s, type, attr.collection?)
+        WalkPlan.new(:scalar, attr, true, rule.name.to_s, type,
+                     attr.collection?)
       end
 
       # Extraction fast path: plain hash fetch for a present, non-blank

data/lib/lutaml/model/error/unsupported_version_error.rb

@@ -0,0 +1,14 @@
+module Lutaml
+  module Model
+    # Raised when version detection reports a model version that no class
+    # in the detected model's family declares (#265).
+    class UnsupportedVersionError < Error
+      def initialize(model_class, version)
+        super(
+          "no model in the #{model_class} family declares version " \
+          "#{version.inspect}",
+        )
+      end
+    end
+  end
+end

data/lib/lutaml/model/evolution_steps.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    # Step collector for the `evolution from:` DSL (#265). Each declared
+    # step is a closure applied in declaration order to the source
+    # document's wire hash; the evolved hash is then parsed by the
+    # target model. All steps are wire-level: they relocate, merge and
+    # drop keys of the old document — the model pipeline never sees a
+    # half-migrated shape.
+    class EvolutionSteps
+      def initialize
+        @steps = []
+      end
+
+      attr_reader :steps
+
+      # Accept a document written with a former wire name for the
+      # current attribute. The current name wins when both appear.
+      def wire_rename(from_key, to:)
+        from_key = from_key.to_s
+        to = to.to_s
+        @steps << lambda do |hash|
+          next hash unless hash.key?(from_key)
+
+          hash[to] = hash.delete(from_key) unless hash.key?(to)
+          hash
+        end
+      end
+
+      # Relocate a former top-level key into a nested position, given
+      # as a dot path ("metadata.name") or an array of segments.
+      # Intermediate objects are created as needed.
+      def wire_move(from_key, to:)
+        path = to.is_a?(::Array) ? to.map(&:to_s) : to.split(".").map(&:to_s)
+        from_key = from_key.to_s
+        @steps << lambda do |hash|
+          value = hash.delete(from_key)
+          next hash if value.nil?
+
+          target = hash
+          path[0...-1].each do |segment|
+            target = (target[segment] ||= {})
+          end
+          target[path[-1]] = value
+          hash
+        end
+      end
+
+      # Combine former keys into one. With `with:`, it receives the
+      # source values in declared order and returns the new value;
+      # without it, the sources must all be hashes and are merged in
+      # declared order.
+      def wire_merge(from_keys, to:, with: nil)
+        keys = from_keys.map(&:to_s)
+        to = to.to_s
+        @steps << lambda do |hash|
+          values = keys.map { |key| hash.delete(key) }
+          hash[to] =
+            if with
+              with.call(*values)
+            elsif values.all?(::Hash)
+              values.reduce { |merged, value| merged.merge(value) }
+            else
+              raise ArgumentError,
+                    "wire_merge requires with: when the merged values " \
+                    "are not all hashes"
+            end
+          hash
+        end
+      end
+
+      # Retire former keys explicitly. Documentation as much as
+      # behavior: an undeclared unknown key keeps the map_unmapped /
+      # drop semantics; a declared one states the vocabulary removed it.
+      def wire_drop(*keys)
+        dropped = keys.map(&:to_s)
+        @steps << lambda do |hash|
+          dropped.each { |key| hash.delete(key) }
+          hash
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/serialize/attribute_definition.rb

@@ -521,6 +521,167 @@ module Lutaml
           end
         end
 
+        # Model evolution (#265): `version 1` (or a semver string)
+        # stamps the model schema version. Subclasses inherit the
+        # nearest ancestor's version; a family is the ancestor chain of
+        # version-declared classes, and detection routes within it.
+        def version(value = nil)
+          return @lutaml_model_version = value if value
+
+          return @lutaml_model_version if defined?(@lutaml_model_version)
+
+          if superclass.is_a?(::Class) &&
+              superclass < ::Lutaml::Model::Serializable
+            return superclass.version
+          end
+
+          nil
+        end
+
+        alias model_version version
+
+        # Wire-level version detection for the family (#265): the block
+        # receives the parsed document hash and returns the version the
+        # document was written against. Declared on the family head;
+        # `from_<format>` routes to the detected version's class before
+        # parsing. Opt-in — without a detector, parsing is unchanged.
+        def detect_version(&block)
+          return @lutaml_version_detector = block if block
+
+          return @lutaml_version_detector if defined?(@lutaml_version_detector)
+
+          if superclass.is_a?(::Class) &&
+              superclass < ::Lutaml::Model::Serializable
+            return superclass.detect_version
+          end
+
+          nil
+        end
+
+        # Declares wire-level migration steps from a former model
+        # version (#265). The block is evaluated on an EvolutionSteps
+        # collector (wire_rename, wire_move, wire_merge, wire_drop);
+        # the steps are applied by `evolve`, in declaration order, to a
+        # copy of the source document's wire hash before the target
+        # model parses it.
+        def evolution(from:, &block)
+          unless from.is_a?(::Class) && from < ::Lutaml::Model::Serializable
+            raise ArgumentError,
+                  "evolution from: must be a Lutaml::Model::Serializable " \
+                  "model class"
+          end
+
+          collector = Lutaml::Model::EvolutionSteps.new
+          collector.instance_eval(&block)
+          lutaml_evolutions[from] = collector.steps.freeze
+          nil
+        end
+
+        def lutaml_evolutions
+          @lutaml_evolutions ||= {}
+        end
+
+        # The class of the family that declares `version == value`.
+        # Walks the ancestor chain nearest-first; raises
+        # UnsupportedVersionError when no family member declares it.
+        def version_class_for(value)
+          klass = self
+          while klass.is_a?(::Class) &&
+              klass < ::Lutaml::Model::Serializable
+            return klass if klass.version == value
+
+            klass = klass.superclass
+          end
+
+          raise ::Lutaml::Model::UnsupportedVersionError.new(self, value)
+        end
+
+        # Migrate a document or instance of a former model version into
+        # this one (#265). The source's wire hash (its own `to_hash`
+        # for an instance) passes through the declared evolution chain
+        # — every family link between the source version and this
+        # class, in order — and the result parses as this model.
+        #
+        # @param source [Hash, Serializable] the old document or model
+        # @param from [Class] the source model class
+        # @param format [Symbol] the key-value format used to parse
+        #   the evolved hash
+        def evolve(source, from:)
+          chain = evolution_chain_from(from)
+          wire = if source.is_a?(::Hash)
+                   Lutaml::Model::Utils.deep_dup(source)
+                 else
+                   source.to_hash
+                 end
+          chain.each do |link_source|
+            steps = evolution_steps_for(link_source)
+            wire = steps.reduce(wire) { |hash, step| step.call(hash) }
+          end
+          from_hash(wire)
+        end
+
+        # Family members nearest-first, self included.
+        def evolution_family
+          members = []
+          klass = self
+          while klass.is_a?(::Class) &&
+              klass < ::Lutaml::Model::Serializable
+            members << klass
+            klass = klass.superclass
+          end
+          members
+        end
+
+        # Shortest declared-evolution path from the source class to
+        # self, as the list of link source classes. Edges are the
+        # family's `evolution from:` declarations. (Public: also serves
+        # introspection of declared family links.)
+        def evolution_chain_from(source_class)
+          return [] if source_class == self
+
+          edges = {}
+          evolution_family.each do |member|
+            member.lutaml_evolutions.each_key do |source|
+              (edges[source] ||= []) << member
+            end
+          end
+
+          parents = { source_class => nil }
+          frontier = [source_class]
+          until frontier.empty? || parents[self]
+            current = frontier.shift
+            (edges[current] || []).each do |target|
+              next if parents.key?(target)
+
+              parents[target] = current
+              frontier << target
+            end
+          end
+
+          unless parents[self]
+            raise ArgumentError,
+                  "no evolution path from #{source_class} to #{self} " \
+                  "is declared"
+          end
+
+          path = []
+          cursor = self
+          while cursor != source_class
+            path.unshift(cursor)
+            cursor = parents[cursor]
+          end
+          path.unshift(source_class)[0...-1]
+        end
+
+        # The family member (nearest-first) that declared steps for the
+        # given link source.
+        def evolution_steps_for(link_source)
+          member = evolution_family.find do |klass|
+            klass.lutaml_evolutions.key?(link_source)
+          end
+          member.lutaml_evolutions[link_source]
+        end
+
         # Define an attribute for the model
         #
         # @param name [Symbol] The attribute name

data/lib/lutaml/model/serialize.rb

@@ -75,6 +75,18 @@ module Lutaml
 
       def self.register_from_format_method(format)
         ClassMethods.define_method(:"from_#{format}") do |data, options = {}|
+          # #265 version routing: with a family detector declared, the
+          # document's version picks the family class that parses it.
+          # Terminates because the routed class resolves the same
+          # detected version to itself and parses directly.
+          detector = detect_version
+          if detector
+            parsed = ::Lutaml::Model::Config.adapter_for(format)
+              .parse(data, options)
+            detected = detector.call(parsed)
+            routed = version_class_for(detected) unless detected.nil?
+            return routed.public_send(:"from_#{format}", data, options) if routed && routed != self
+          end
           from(format, data, options)
         end
 

data/lib/lutaml/model/union.rb

@@ -97,7 +97,23 @@ module Lutaml
                        end
               return [member, casted] unless casted == :no_match
             end
-            nil
+
+            lenient_model_member(value, members, format, register)
+          end
+
+          # With exactly one model member, a Hash that also carries unmapped
+          # keys still conforms: unknown keys are ignored by every non-union
+          # model attribute, and strict coverage would silently drop the
+          # whole value. With several model members the strict key-coverage
+          # check stays in charge — coverage is what discriminates between
+          # them. Plain-Ruby assignment keeps the strict constructor path.
+          def lenient_model_member(value, members, format, register)
+            return nil unless value.is_a?(::Hash)
+            return nil if format.nil?
+            return nil unless members.one? { |member| model_member?(member) }
+
+            member = members.find { |candidate| model_member?(candidate) }
+            [member, member.apply_mappings(value, format, register: register)]
           end
 
           # Whether a compiled mapping rule's attribute is a union — the single

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.123"
+    VERSION = "0.8.125"
   end
 end

data/lib/lutaml/model.rb

@@ -46,6 +46,7 @@ module Lutaml
     autoload :NamespaceBinding, "#{__dir__}/model/register/namespace_binding"
     autoload :ModelTreeImporter, "#{__dir__}/model/register/model_tree_importer"
     autoload :Transformation, "#{__dir__}/model/transformation"
+    autoload :EvolutionSteps, "#{__dir__}/model/evolution_steps"
     autoload :CompiledRule, "#{__dir__}/model/compiled_rule"
     autoload :FormatRegistry, "#{__dir__}/model/format_registry"
     autoload :OneEntryCache, "#{__dir__}/model/one_entry_cache"
@@ -161,6 +162,8 @@ module Lutaml
     autoload :NoRootMappingError, "#{__dir__}/model/error/no_root_mapping_error"
     autoload :ImportModelWithRootError,
              "#{__dir__}/model/error/import_model_with_root_error"
+    autoload :UnsupportedVersionError,
+             "#{__dir__}/model/error/unsupported_version_error"
     autoload :InvalidChoiceRangeError,
              "#{__dir__}/model/error/invalid_choice_range_error"
     autoload :UnknownSequenceMappingError,

data/spec/lutaml/model/child_mappings_absent_key_spec.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# A child_mappings rule whose wire key is absent crashed translate_mappings
+# with an internal NoMethodError (nil.map) wrapped as InvalidFormatError.
+# An absent key means the attribute keeps its uninitialized/default state,
+# exactly like every other rule kind.
+RSpec.describe "child_mappings rule with an absent key" do
+  let(:schema_class) do
+    Class.new(Lutaml::Model::Serializable) do
+      attribute :id, :string
+      attribute :path, :string
+    end
+  end
+
+  let(:model_class) do
+    schemas = schema_class
+    Class.new(Lutaml::Model::Serializable) do
+      attribute :type, :string
+      attribute :schemas, schemas, collection: true
+
+      key_value do
+        map "type", to: :type
+        map "schemas", to: :schemas,
+                       child_mappings: {
+                         id: :key,
+                         path: %i[path link],
+                       }
+      end
+    end
+  end
+
+  before { stub_const("ChildMapAbsentModel", model_class) }
+
+  it "parses without the key, leaving the attribute unset" do
+    model = ChildMapAbsentModel.from_json('{"type":"object"}')
+
+    expect(model.type).to eq("object")
+    expect(model.schemas).to be_nil
+  end
+
+  it "still translates when the key is present" do
+    model = ChildMapAbsentModel.from_json(
+      '{"type":"object","schemas":{' \
+      '"sch1":{"path":{"link":"https://example.com"}}}}',
+    )
+
+    expect(model.schemas.size).to eq(1)
+    expect(model.schemas.first.id).to eq("sch1")
+    expect(model.schemas.first.path).to eq("https://example.com")
+  end
+end

data/spec/lutaml/model/evolution_spec.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# #265: model evolution — version metadata, wire-level migration steps
+# between model versions, and family version detection. The migration
+# steps operate on the source document's wire hash (deep-copied); the
+# evolved hash parses as the target model through the hash format.
+RSpec.describe "model evolution" do
+  let(:v1_class) do
+    Class.new(Lutaml::Model::Serializable) do
+      version 1
+
+      attribute :author, :string
+      attribute :name, :string
+      attribute :first_name, :string
+      attribute :last_name, :string
+      attribute :tag, :string
+      attribute :deprecated_field, :string
+
+      key_value do
+        map "author", to: :author
+        map "name", to: :name
+        map "first_name", to: :first_name
+        map "last_name", to: :last_name
+        map "tag", to: :tag
+        map "deprecated_field", to: :deprecated_field
+      end
+    end
+  end
+
+  let(:v2_class) do
+    v1 = v1_class
+    Class.new(v1) do
+      version 2
+
+      attribute :creator, :string
+      attribute :full_name, :string
+      attribute :tags, :string, collection: true
+      attribute :metadata_name, :string
+
+      key_value do
+        map "creator", to: :creator
+        map "full_name", to: :full_name
+        map "tags", to: :tags
+        map "metadata", to: :metadata_name,
+                        child_mappings: { metadata_name: :name }
+        map "deprecated_field", to: :deprecated_field, serialize: false
+      end
+
+      evolution from: v1 do
+        wire_rename "author", to: "creator"
+        wire_rename "tag", to: "tags"
+        wire_merge %w[first_name last_name], to: "full_name",
+                                             with: ->(first, last) { [first, last].compact.join(" ") }
+        wire_drop "first_name", "last_name", "deprecated_field"
+      end
+    end
+  end
+
+  before do
+    stub_const("EvolutionDocV1", v1_class)
+    stub_const("EvolutionDocV2", v2_class)
+  end
+
+  it "stamps and inherits the model version" do
+    expect(EvolutionDocV1.model_version).to eq(1)
+    expect(EvolutionDocV2.model_version).to eq(2)
+  end
+
+  it "migrates a v1 hash into a v2 model through declared steps" do
+    v2 = EvolutionDocV2.evolve(
+      { "author" => "Ruth", "first_name" => "Ada", "last_name" => "L" },
+      from: EvolutionDocV1,
+    )
+
+    expect(v2).to be_a(EvolutionDocV2)
+    expect(v2.creator).to eq("Ruth")
+    expect(v2.full_name).to eq("Ada L")
+  end
+
+  it "migrates a v1 instance through its own wire hash" do
+    old = EvolutionDocV1.from_json(
+      '{"author":"Ruth","tag":"core","deprecated_field":"gone"}',
+    )
+    v2 = EvolutionDocV2.evolve(old, from: EvolutionDocV1)
+
+    expect(v2.creator).to eq("Ruth")
+    expect(v2.tags).to eq(["core"])
+  end
+
+  it "does not mutate the caller's source hash" do
+    source = { "author" => "Ruth", "first_name" => "Ada" }
+    EvolutionDocV2.evolve(source, from: EvolutionDocV1)
+
+    expect(source).to eq("author" => "Ruth", "first_name" => "Ada")
+  end
+
+  it "relocates keys with wire_move" do
+    mover = Class.new(EvolutionDocV1) do
+      version 3
+      attribute :meta, :hash
+
+      key_value do
+        map "meta", to: :meta
+      end
+
+      evolution from: EvolutionDocV2 do
+        wire_move "creator", to: "meta.creator"
+      end
+    end
+    stub_const("EvolutionDocV3", mover)
+
+    v3 = mover.evolve(
+      { "creator" => "Ruth", "name" => "n" },
+      from: EvolutionDocV2,
+    )
+
+    expect(v3.meta).to eq("creator" => "Ruth")
+  end
+
+  it "composes chains v1 -> v2 -> v3" do
+    mover = Class.new(EvolutionDocV2) do
+      version 3
+
+      evolution from: EvolutionDocV2 do
+        wire_drop "tag"
+      end
+    end
+    stub_const("EvolutionDocV3Chain", mover)
+
+    v3 = mover.evolve(
+      { "author" => "Ruth", "first_name" => "Ada", "tag" => "x" },
+      from: EvolutionDocV1,
+    )
+
+    expect(v3).to be_a(EvolutionDocV3Chain)
+    expect(v3.creator).to eq("Ruth")
+  end
+
+  it "raises when no evolution path is declared" do
+    unrelated = Class.new(Lutaml::Model::Serializable) do
+      version 9
+      attribute :x, :string
+      key_value { map "x", to: :x }
+    end
+    stub_const("EvolutionUnrelated", unrelated)
+
+    expect do
+      EvolutionUnrelated.evolve({ "x" => 1 }, from: EvolutionDocV1)
+    end.to raise_error(
+      ArgumentError,
+      /no evolution path from EvolutionDocV1 to EvolutionUnrelated/,
+    )
+  end
+
+  describe "version detection" do
+    let(:detecting_class) do
+      Class.new(v2_class) do
+        detect_version do |doc|
+          doc["schema_version"] || 1
+        end
+      end
+    end
+
+    before { stub_const("EvolutionDetecting", detecting_class) }
+
+    it "routes an older document to its own version's model" do
+      parsed = EvolutionDetecting.from_json(
+        '{"schema_version":1,"author":"Ruth"}',
+      )
+
+      expect(parsed).to be_a(EvolutionDocV1)
+      expect(parsed.author).to eq("Ruth")
+    end
+
+    it "parses a current document as itself" do
+      parsed = EvolutionDetecting.from_json(
+        '{"schema_version":2,"creator":"Ruth"}',
+      )
+
+      expect(parsed).to be_a(EvolutionDetecting)
+      expect(parsed.creator).to eq("Ruth")
+    end
+
+    it "raises on a version no family member declares" do
+      expect do
+        EvolutionDetecting.from_json('{"schema_version":42}')
+      end.to raise_error(
+        Lutaml::Model::UnsupportedVersionError,
+        /version 42/,
+      )
+    end
+  end
+
+  describe "models without evolution declarations" do
+    it "parses unchanged" do
+      model = v1_class.from_json('{"author":"Ruth"}')
+
+      expect(model.author).to eq("Ruth")
+      expect(v1_class.model_version).to eq(1)
+    end
+  end
+end

data/spec/lutaml/model/union_attribute_spec.rb

@@ -686,14 +686,27 @@ RSpec.describe "Union-typed attributes (issue #190)" do
       expect(parsed.value).to be(true)
     end
 
-    it "returns nil only when no member conforms at all" do
+    it "builds the lone model member even when no key maps (#989: " \
+       "non-union parity)" do
       holder = Class.new(Lutaml::Model::Serializable) do
         attribute :value, [ExtendedShape, :boolean]
         key_value { map "value", to: :value }
       end
       stub_const("ExtendedHolderNinetyEight", holder)
 
-      expect(holder.from_json('{"value":{"unrelated":1}}').value).to be_nil
+      value = holder.from_json('{"value":{"unrelated":1}}').value
+
+      expect(value).to be_a(ExtendedShape)
+    end
+
+    it "returns nil when no member conforms at all" do
+      holder = Class.new(Lutaml::Model::Serializable) do
+        attribute :value, [ExtendedShape, :boolean]
+        key_value { map "value", to: :value }
+      end
+      stub_const("ExtendedHolderNinetyEightB", holder)
+
+      expect(holder.from_json('{"value":3}').value).to be_nil
     end
   end
 

data/spec/lutaml/model/union_lenient_model_spec.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Regression spec for issue #987: with a single model member in a union,
+# a Hash carrying keys the model does not map must still conform. Unknown
+# keys are ignored by every non-union model attribute; strict key
+# coverage silently returned nil for the whole attribute instead.
+module UnionLenientModelSpec
+  class Extensible < Lutaml::Model::Serializable
+    attribute :type, :string
+    attribute :strict_properties, :boolean
+
+    key_value do
+      map "type", to: :type
+      map "strictProperties", to: :strict_properties
+    end
+  end
+
+  class Holder < Lutaml::Model::Serializable
+    attribute :value, [Extensible, :boolean]
+
+    key_value do
+      map "value", to: :value
+    end
+  end
+
+  class Other < Lutaml::Model::Serializable
+    attribute :celsius, :float
+
+    key_value do
+      map "celsius", to: :celsius
+    end
+  end
+
+  class TwoModelHolder < Lutaml::Model::Serializable
+    attribute :value, [Extensible, Other]
+
+    key_value do
+      map "value", to: :value
+    end
+  end
+
+  RSpec.describe "Union with a single model member accepts unmapped keys" do
+    it "builds the model when the hash carries unmapped keys" do
+      value = Holder.from_json('{"value":{"type":"string","x-ext":1}}').value
+
+      expect(value).to be_a(Extensible)
+      expect(value.type).to eq("string")
+    end
+
+    it "still accepts hashes with mapped keys only" do
+      value = Holder.from_json('{"value":{"type":"string"}}').value
+
+      expect(value).to be_a(Extensible)
+      expect(value.type).to eq("string")
+    end
+
+    it "keeps boolean members working" do
+      expect(Holder.from_json('{"value":true}').value).to be(true)
+      expect(Holder.from_json('{"value":false}').value).to be(false)
+    end
+
+    it "dispatches to the first model member with a mapped key across " \
+       "several members" do
+      json = '{"value":{"type":"string","celsius":1.0}}'
+
+      value = TwoModelHolder.from_json(json).value
+
+      expect(value).to be_a(Extensible)
+      expect(value.type).to eq("string")
+    end
+
+    it "still requires a match when nothing conforms" do
+      expect(Holder.from_json('{"value":3}').value).to be_nil
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.123
+  version: 0.8.125
 platform: ruby
 authors:
 - Ribose Inc.
@@ -500,9 +500,11 @@ files:
 - lib/lutaml/model/error/unknown_sequence_mapping_error.rb
 - lib/lutaml/model/error/unknown_type_error.rb
 - lib/lutaml/model/error/unresolvable_type_error.rb
+- lib/lutaml/model/error/unsupported_version_error.rb
 - lib/lutaml/model/error/validation_error.rb
 - lib/lutaml/model/error/validation_failed_error.rb
 - lib/lutaml/model/errors.rb
+- lib/lutaml/model/evolution_steps.rb
 - lib/lutaml/model/finalization_cache.rb
 - lib/lutaml/model/format_registry.rb
 - lib/lutaml/model/global_context.rb
@@ -1716,6 +1718,7 @@ files:
 - spec/lutaml/model/cardinality_strict_spec.rb
 - spec/lutaml/model/cast_element_form_spec.rb
 - spec/lutaml/model/cdata_spec.rb
+- spec/lutaml/model/child_mappings_absent_key_spec.rb
 - spec/lutaml/model/choice_restrict_spec.rb
 - spec/lutaml/model/choice_spec.rb
 - spec/lutaml/model/cli_spec.rb
@@ -1750,6 +1753,7 @@ files:
 - spec/lutaml/model/dynamic_attribute_spec.rb
 - spec/lutaml/model/encoding_spec.rb
 - spec/lutaml/model/enum_spec.rb
+- spec/lutaml/model/evolution_spec.rb
 - spec/lutaml/model/except_spec.rb
 - spec/lutaml/model/finalization_cache_spec.rb
 - spec/lutaml/model/from_json_scalar_cast_spec.rb
@@ -1868,6 +1872,7 @@ files:
 - spec/lutaml/model/uninitialized_class_deep_dup_spec.rb
 - spec/lutaml/model/uninitialized_class_spec.rb
 - spec/lutaml/model/union_attribute_spec.rb
+- spec/lutaml/model/union_lenient_model_spec.rb
 - spec/lutaml/model/union_spec.rb
 - spec/lutaml/model/unregistered_context_resolution_spec.rb
 - spec/lutaml/model/utils_spec.rb