lutaml-model 0.8.123 → 0.8.124

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d77a19ece999a4de97c03776b3f56bc31eb217fb14904362eef4c98b4623be6
-  data.tar.gz: b76ef3e5de721b3e94a02dbac605c61fe3ca44fe97388b8fca1ec4645c3ab494
+  metadata.gz: f4c03c6aacd7f243f8c919c1561cada699b4d6a06fa1fa7f48e7847787dcbef2
+  data.tar.gz: bdadc3e2abadd6df36b913d19ec281771e5ea4b68ec74f58b1566f93a6053242
 SHA512:
-  metadata.gz: 3a03373b96d83e69500cbd2371557f5ced955e85964b3a92340e8bf3cb4da0b45ea3f83ed59fc6f47e410661c5a2e0ca0b9a5d2db6d890ce9d192ed35ccda2c1
-  data.tar.gz: 6675bdd426008a94d3e1367b584d3ce92e242b6d6e6e3a85c1e7afc544ab57cce7da847a7af53c9a3f11bd1bfb4f3b49cefb1032eb8157a5e2ddee32b4761545
+  metadata.gz: '09ac4538324403ddc363c1b75ecedb9499a5361c399894287c83ec1ffb52cd4169cc6ea050f1dd4242c6d834b5df55845e17fa1b0c2e7b10b21c6639a52c7c26'
+  data.tar.gz: 8322eeba63f6c0b4ff546629bb81801a80d9b19b3ee13ab1fd72d5265c52b7f3248f28c498b59f3b6eb135fbe78cb73632f0cdd609cab821a5a792fd374251a6

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

@@ -753,6 +753,12 @@ partition = nil)
         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? && (rule.hash_mappings || rule.child_mappings)
+
         value = translate_mappings(value, rule.hash_mappings, attr, format,
                                    instance)
         unless rule.hash_mappings

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/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.123"
+    VERSION = "0.8.124"
   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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.123
+  version: 0.8.124
 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