lutaml-model 0.8.133 → 0.8.135

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ea94bb734406bacfb047edb9c580a3f224f19c497b4f506440da60d381cd1bf
-  data.tar.gz: 96f7c71f51a0ec8b863eec77b894ec611ff3a4e8b59354ec9b477e6470258852
+  metadata.gz: 51feb7853a13baba31f30840887bffdaa44dd44e7fe29c31e8e5fe1657847db7
+  data.tar.gz: 1464e32175a9ad90844529f27703040ee6e363184ce86c6edb7d6bcd560d287a
 SHA512:
-  metadata.gz: 4e61d4a02ebb21a794de64a0301a3489b045b8562ce8e1a8f3522b227bea1632882e7e09d1ce6fe18352d41c8fe62d2a5d9652b315dda76a220cbd30fe15f3cf
-  data.tar.gz: 60c206b080775425586980a1f3b484db2280be9e9b73bc365237210f64c90fc3faa80f1f9e9a42e94259a9a83ba1edab1ceecc25bb804147ecd3e31ead97c15d
+  metadata.gz: 5da32b5d0a99d97d60db8b7a0936cd1ad550779246397446d08fdc39082b5e6b847f9bf9070ea7c424df2597a4dc9ee683256b127f8425e25c736be318646d66
+  data.tar.gz: 50614e126790cd21f7a377d6dd777125c1ea8d90275323bb213607e06a747620758323b42c75a1b73205adc9396663ce30eda8fb2f6169bc2025ca3e48812548

data/docs/key_value_data_model.adoc

@@ -446,6 +446,60 @@ Model.to_json  # Uses KeyValue::Transformation → KeyValueElement → Adapter
 Model.to_json  # Uses Hash transformation → Adapter
 ----
 
+== The custom `to:` handler contract
+
+A mapping rule that declares `with: { to: :method_name }` receives the
+output document as its second argument and mutates it in place
+(mutation-only — the handler's return value is ignored, lutaml-model
+#892). Which object the handler receives depends on the serialization
+lane:
+
+* The transformation lane — the default path — hands the handler a
+  scratch `Lutaml::KeyValue::DataModel::Element` keyed with the rule's
+  serialized name. After the handler runs, only the element's payload
+  (the merged children, or the direct value hash) is merged into the
+  output.
+* The legacy hash lane (used when no compiled transformation is
+  available, e.g. cyclic model graphs) hands the handler the output
+  `Hash` itself.
+
+=== The portable subset
+
+Write handlers against the hash-like subset — it behaves identically on
+both lanes:
+
+[source,ruby]
+----
+key_value do
+  map "locality", to: :type, with: { to: :locality_to_yaml }
+end
+
+def locality_to_yaml(model, doc)
+  doc["locality"] = {}
+  doc["locality"]["type"] = model.locality.type
+  doc["locality"]["reference_from"] = model.locality.reference_from
+end
+----
+
+On the transformation lane, `doc["locality"]` reads through to the
+child's own value object, so chained writes mutate it in place; on the
+legacy lane the same lines are plain Hash writes.
+
+=== Element-only surface
+
+`doc.value =`, `doc.add_child`, and reads of `doc.value` exist only on
+the transformation lane's Element. A handler that uses them breaks if
+the legacy lane ever serves the model (cyclic graphs, mapping
+overrides). Prefer the hash-like subset unless the handler is known to
+run only on the transformation lane.
+
+=== Merge semantics
+
+After the handler runs, the document's payload merges into the output
+only when it is a `Hash` — an untouched document contributes nothing,
+and scalar or array payloads are dropped (matching the pre-0.8.74
+behavior).
+
 == Serialization Flow
 
 === Complete Data Flow

data/lib/lutaml/model/union.rb

@@ -98,7 +98,26 @@ module Lutaml
               return [member, casted] unless casted == :no_match
             end
 
-            lenient_model_member(value, members, format, register)
+            widest_model_member(value, members, format, register) ||
+              lenient_model_member(value, members, format, register)
+          end
+
+          # No member maps every key, so the hash carries keys no rule claims
+          # (extension keywords, forward-compatible vocabularies): the model
+          # member mapping the most of its keys, the earlier one on a tie, as
+          # the keys no rule claims are ignored outside a union (#987).
+          def widest_model_member(value, members, format, register)
+            keys = input_keys(value, format)
+            return nil if keys.nil? || keys.empty?
+
+            counts = members.select { |member| model_member?(member) }.to_h do |member|
+              field_names = member_field_names(member, format, register)
+              [member, keys.count { |key| field_names.include?(key) }]
+            end
+            member, count = counts.max_by.with_index { |(_, mapped), index| [mapped, -index] }
+            return nil if member.nil? || count.zero?
+
+            [member, build_model(member, value, format, register)]
           end
 
           # With exactly one model member, a Hash that also carries unmapped
@@ -170,14 +189,12 @@ module Lutaml
             member.is_a?(::Class) && member.include?(Serialize)
           end
 
-          # Structural selection: at least one input key maps to one of the
-          # member's mapped fields. Keys no rule claims are ignored exactly
-          # as they are when the same hash reaches the model outside a
-          # union — extension keys (x-** vendor keywords, forward-compatible
-          # vocabularies) must not defeat dispatch (#987). Once selected,
-          # field values cast leniently via the member's normal path. An
-          # existing member instance conforms as-is, keeping conformance
-          # idempotent — values can re-enter casting (e.g. a value
+          # Structural (key-coverage) selection: every input key maps to one of
+          # the member's mapped fields, which is what tells members sharing a
+          # key apart. A hash no member covers falls to widest_model_member.
+          # Once selected, field values cast leniently via the member's normal
+          # path. An existing member instance conforms as-is, keeping
+          # conformance idempotent — values can re-enter casting (e.g. a value
           # transformer builds the member before the cast runs).
           def conform_model(member, value, format, register)
             return value if value.is_a?(member)
@@ -186,13 +203,17 @@ module Lutaml
             return :no_match if keys.nil? || keys.empty?
 
             field_names = member_field_names(member, format, register)
-            return :no_match unless keys.any? do |key|
+            return :no_match unless keys.all? do |key|
               field_names.include?(key)
             end
 
-            # Plain-Ruby assignment (format nil) builds straight from the
-            # attribute hash, mirroring how non-union model attributes accept
-            # `Model.new(child: { ... })`; a format builds via the mappings.
+            build_model(member, value, format, register)
+          end
+
+          # Plain-Ruby assignment (format nil) builds straight from the
+          # attribute hash, mirroring how non-union model attributes accept
+          # `Model.new(child: { ... })`; a format builds via the mappings.
+          def build_model(member, value, format, register)
             return member.new(value) if format.nil?
 
             member.apply_mappings(value, format, register: register)

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.133"
+    VERSION = "0.8.135"
   end
 end

data/lib/lutaml/xml/schema/xsd/redefine.rb

@@ -19,12 +19,12 @@ module Lutaml
             namespace Lutaml::Xml::Schema::XsdNamespace
 
             map_attribute :id, to: :id
-            map_attribute :schema_location, to: :schema_path
+            map_attribute "schemaLocation", to: :schema_path
             map_element :group, to: :group
             map_element :annotation, to: :annotation
-            map_element :simpleType, to: :simpleType
-            map_element :complexType, to: :complexType
-            map_element :attributeGroup, to: :attributeGroup
+            map_element :simpleType, to: :simple_type
+            map_element :complexType, to: :complex_type
+            map_element :attributeGroup, to: :attribute_group
           end
 
           Lutaml::Xml::Schema::Xsd.register_model(self, :redefine)

data/spec/lutaml/model/union_attribute_spec.rb

@@ -710,6 +710,76 @@ RSpec.describe "Union-typed attributes (issue #190)" do
     end
   end
 
+  describe "model members that share a key" do
+    # Two members both map "source"; only their other keys tell them
+    # apart. The member mapping every key wins over an earlier one that
+    # maps only the shared key, as before #987; with an extension key
+    # neither maps every key, so the member mapping the most keys wins.
+    let(:report) do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :source, :string
+        attribute :issues, :string, collection: true
+        key_value do
+          map "source", to: :source
+          map "issues", to: :issues
+        end
+      end
+    end
+
+    let(:conversion) do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :source, :string
+        attribute :target, :string
+        key_value do
+          map "source", to: :source
+          map "target", to: :target
+        end
+      end
+    end
+
+    let(:holder) do
+      members = [report, conversion]
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :result, members
+        key_value { map "result", to: :result }
+      end
+    end
+
+    before do
+      stub_const("SharedKeyReport", report)
+      stub_const("SharedKeyConversion", conversion)
+      stub_const("SharedKeyHolder", holder)
+    end
+
+    it "selects the later member whose fields cover every key" do
+      parsed = holder.from_json('{"result":{"source":"a.emf","target":"svg"}}')
+
+      expect(parsed.result).to be_a(conversion)
+      expect(parsed.result.target).to eq("svg")
+    end
+
+    it "keeps the earlier member when it covers every key" do
+      parsed = holder.from_json('{"result":{"source":"a.emf","issues":["m"]}}')
+
+      expect(parsed.result).to be_a(report)
+      expect(parsed.result.issues).to eq(["m"])
+    end
+
+    it "selects the member mapping the most keys when an extension key is present" do
+      parsed = holder.from_json(
+        '{"result":{"source":"a.emf","target":"svg","x-ext":1}}',
+      )
+
+      expect(parsed.result).to be_a(conversion)
+    end
+
+    it "keeps declared order when members map equally many keys" do
+      parsed = holder.from_json('{"result":{"source":"a.emf","x-ext":1}}')
+
+      expect(parsed.result).to be_a(report)
+    end
+  end
+
   describe "value transformers (cast idempotence)" do
     it "keeps a model member built by transform: before the cast runs" do
       reading = UnionAttributeSpec::TransformedReading.from_yaml(<<~YAML)

data/spec/lutaml/xml/schema/xsd/mapping_integrity_spec.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "lutaml/xml"
+require "lutaml/xml/schema/xsd"
+
+# The XSD schema-object classes carry hand-written XML mappings; a `to:`
+# that does not name a declared attribute compiles fine and then crashes
+# at parse time with "Attribute '...' not found" — for ANY document that
+# contains the class, because the rule loop validates every mapping rule
+# against the instance, not only the children present (#1025: redefine
+# shipped to: :simpleType / :complexType / :attributeGroup against
+# simple_type / complex_type / attribute_group). This sweep pins every
+# registered model's element and attribute rules to declared attributes
+# so the whole typo family fails here, at spec time.
+RSpec.describe "XSD schema model mapping integrity" do
+  it "maps every element rule of every registered model to a declared attribute" do
+    broken = []
+
+    Lutaml::Xml::Schema::Xsd.register.models.each_value do |klass|
+      next unless klass.is_a?(Class) && klass.include?(Lutaml::Model::Serialize)
+
+      mapping = klass.mappings_for(:xml)
+      mapping.mapping_elements_hash.each_value do |rule_or_array|
+        Array(rule_or_array).each do |rule|
+          unless klass.attributes.key?(rule.to)
+            broken << "#{klass.name}: map_element #{rule.name.inspect} -> " \
+                      "#{rule.to.inspect}"
+          end
+        end
+      end
+    end
+
+    expect(broken).to be_empty, <<~MSG
+      mapping rules point at undeclared attributes:
+      #{broken.join("\n")}
+    MSG
+  end
+
+  it "maps every attribute rule of every registered model to a declared attribute" do
+    broken = []
+
+    Lutaml::Xml::Schema::Xsd.register.models.each_value do |klass|
+      next unless klass.is_a?(Class) && klass.include?(Lutaml::Model::Serialize)
+
+      mapping = klass.mappings_for(:xml)
+      mapping.mapping_attributes_hash.each_value do |rule_or_array|
+        Array(rule_or_array).each do |rule|
+          unless klass.attributes.key?(rule.to)
+            broken << "#{klass.name}: map_attribute #{rule.name.inspect} -> " \
+                      "#{rule.to.inspect}"
+          end
+        end
+      end
+    end
+
+    expect(broken).to be_empty, <<~MSG
+      mapping rules point at undeclared attributes:
+      #{broken.join("\n")}
+    MSG
+  end
+
+  # #1025: the regression that motivated the sweep — a redefine with a
+  # group child parses, and each redefined member kind lands on its
+  # declared attribute.
+  it "parses xs:redefine with group, simpleType, complexType and attributeGroup" do
+    doc = Lutaml::Xml::Schema::Xsd.parse(<<~XSD)
+      <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+        <xsd:redefine schemaLocation="base.xsd">
+          <xsd:group name="g">
+            <xsd:choice><xsd:element name="e1"/></xsd:choice>
+          </xsd:group>
+          <xsd:simpleType name="st">
+            <xsd:restriction base="xsd:string"/>
+          </xsd:simpleType>
+          <xsd:complexType name="ct">
+            <xsd:sequence><xsd:element name="x"/></xsd:sequence>
+          </xsd:complexType>
+          <xsd:attributeGroup name="ag"/>
+        </xsd:redefine>
+      </xsd:schema>
+    XSD
+
+    redefined = doc.redefine.first
+
+    expect(redefined.group.name).to eq("g")
+    expect(redefined.simple_type.name).to eq("st")
+    expect(redefined.complex_type.name).to eq("ct")
+    expect(redefined.attribute_group.name).to eq("ag")
+    expect(redefined.schema_path).to eq("base.xsd")
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.133
+  version: 0.8.135
 platform: ruby
 authors:
 - Ribose Inc.
@@ -2056,6 +2056,7 @@ files:
 - spec/lutaml/xml/schema/xsd/liquid_methods/schema_spec.rb
 - spec/lutaml/xml/schema/xsd/liquid_methods/simple_content_spec.rb
 - spec/lutaml/xml/schema/xsd/list_simple_type_spec.rb
+- spec/lutaml/xml/schema/xsd/mapping_integrity_spec.rb
 - spec/lutaml/xml/schema/xsd/namespace_uri_remapping_spec.rb
 - spec/lutaml/xml/schema/xsd/schema_helper_methods_spec.rb
 - spec/lutaml/xml/schema/xsd/schema_mapping_spec.rb