lutaml-model 0.8.132 → 0.8.134

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83ece4646bc4f2ecd052f6ba5edf994cb512b4be3a08e8a1778c5b357daab424
-  data.tar.gz: 9bac20d16559163de764a7148974724c199cacbce0d88d945b932c7d36ccaa19
+  metadata.gz: 250473959d5b49e40ab480a2acf1e708d2cac1f8d5b092995be03821bc758122
+  data.tar.gz: 59fc186602fae873d070d23baca950a2330a07abbb251acd16b3a63803877a93
 SHA512:
-  metadata.gz: 27120683de1ff8d9c95049e683dffdf302aa43edf9a4e5e6debda189df3903fdf98f4722200eb4106285e86dfabb170b77fcaea3313c6e1a8e8e548ec2db0eab
-  data.tar.gz: 26a84cc1b288f7b829c1bdb44360adc7211843e506d1d51c1f416c411636fa6099dee79fd26d4d41a7e22b5eaf3ef1510d9580dbe49318ac8c2b9e02b80974bc
+  metadata.gz: 82c2a11ef5c20e8342280054b0053e7d07fcca92b71effc4224d6b006889f3873026890d894b98a0791add12444e1cb87cddab51ece3eee47f2d08e8a53106c0
+  data.tar.gz: 95ec3912247f014bc20a9bf2f3ec39a3fc1b0bdf5eeb2b932f55612446b5f3c45af21e6b37c28682b52541e842bc68b7099ce361b6b8184f93265e8254779873

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/type/hash.rb

@@ -18,22 +18,37 @@ module Lutaml
         end
 
         def self.normalize_hash(hash)
-          return hash["text"] if hash.keys == ["text"]
+          xml = hash.is_a?(Lutaml::Model::MappingHash)
+          return hash["text"] if text_node?(hash)
 
-          hash = hash.to_h if hash.is_a?(Lutaml::Model::MappingHash)
+          hash = hash.to_h if xml
 
-          normalized_hash = hash.transform_values do |value|
+          normalized = hash.transform_values do |value|
             normalize_value(value)
           end
+          xml ? (normalized["elements"] || normalized) : normalized
+        end
 
-          normalized_hash["elements"] || normalized_hash
+        # {"text" => string} is the XML text-node convention and
+        # collapses to the string. Any other "text" key — structured
+        # values, or appearing alongside other keys in non-XML data —
+        # is ordinary data and must round-trip verbatim
+        # (lutaml/lutaml-model#1013).
+        def self.text_node?(hash)
+          # ::String — unqualified String resolves to Type::String here
+          hash.is_a?(::Hash) && hash.keys == ["text"] &&
+            hash["text"].is_a?(::String)
         end
 
         def self.normalize_value(value)
           return value unless value.is_a?(::Hash)
 
           nested = normalize_hash(value)
-          nested.is_a?(::Hash) ? nested.except("text") : nested
+          if value.is_a?(Lutaml::Model::MappingHash) && nested.is_a?(::Hash)
+            nested.except("text")
+          else
+            nested
+          end
         end
 
         def self.serialize(value)

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.132"
+    VERSION = "0.8.134"
   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/lib/lutaml/xml/serialization/instance_methods.rb

@@ -178,8 +178,13 @@ module Lutaml
                     elsif val.is_a?(Lutaml::Model::Serializable)
                       collection_indices[attr_name] += 1
                       collection_indices[attr_name] == 1 ? val : nil
+                    else
+                      # Scalar mapped elements (e.g. a string-valued
+                      # <main>) are part of the mixed content too.
+                      collection_indices[attr_name] += 1
+                      val
                     end
-              yield(obj) if obj
+              yield(obj) unless obj.nil? || (obj.is_a?(String) && obj.empty?)
             end
           end
 

data/spec/lutaml/model/mixed_content_spec.rb

@@ -1449,4 +1449,36 @@ RSpec.describe "MixedContent" do
                       described_class
     end
   end
+
+  describe "each_mixed_content with string-valued mapped elements" do
+    it "yields scalar mapped elements, not only Arrays and Serializable children" do
+      xml = "<title-wrap><main>Test Document</main></title-wrap>"
+      model = MixedContentSpec::TitleWrap.from_xml(xml)
+
+      expect(model.main).to eq("Test Document")
+
+      yielded = model.each_mixed_content.to_a
+      expect(yielded).to include("Test Document")
+    end
+
+    it "skips empty scalar values" do
+      xml = "<title-wrap><main></main></title-wrap>"
+      model = MixedContentSpec::TitleWrap.from_xml(xml)
+
+      yielded = model.each_mixed_content.to_a
+      expect(yielded).not_to include("")
+    end
+  end
+end
+
+module MixedContentSpec
+  class TitleWrap < Lutaml::Model::Serializable
+    attribute :main, :string
+
+    xml do
+      element "title-wrap"
+      mixed_content
+      map_element "main", to: :main
+    end
+  end
 end

data/spec/lutaml/model/type/hash_spec.rb

@@ -6,11 +6,30 @@ RSpec.describe Lutaml::Model::Type::Hash do
       expect(described_class.cast(nil)).to be_nil
     end
 
-    it "returns text content from hash with only text key" do
-      hash = { "text" => "content" }
+    it "returns text content from a MappingHash with only text key" do
+      hash = Lutaml::Model::MappingHash.new
+      hash["text"] = "content"
       expect(described_class.cast(hash)).to eq "content"
     end
 
+    # lutaml/lutaml-model#1013: a "text" key holding structured data
+    # (or appearing alongside other keys in non-XML data) is ordinary
+    # data and must round-trip verbatim
+    it "preserves a structured text key from a plain hash" do
+      hash = { "text" => { "type" => "string", "description" => "y" } }
+      expect(described_class.cast(hash)).to eq hash
+    end
+
+    it "preserves text alongside other keys in a plain hash" do
+      hash = { "text" => "content", "other" => "value" }
+      expect(described_class.cast(hash)).to eq hash
+    end
+
+    it "preserves an elements key from a plain hash" do
+      hash = { "elements" => [{ "a" => 1 }] }
+      expect(described_class.cast(hash)).to eq hash
+    end
+
     it "normalizes MappingHash to regular Hash" do
       mapping_hash = Lutaml::Model::MappingHash.new
       mapping_hash["key"] = "value"
@@ -18,28 +37,29 @@ RSpec.describe Lutaml::Model::Type::Hash do
     end
 
     context "with nested hashes" do
-      let(:input) do
-        {
-          "key1" => {
-            "text" => "content1",
-            "other" => "value1",
-          },
-          "key2" => {
-            "text" => "content2",
-            "other" => "value2",
-          },
-        }
-      end
-
-      let(:expected_hash) do
-        {
+      it "filters out text keys from nested MappingHashes" do
+        child1 = Lutaml::Model::MappingHash.new
+        child1["text"] = "content1"
+        child1["other"] = "value1"
+        child2 = Lutaml::Model::MappingHash.new
+        child2["text"] = "content2"
+        child2["other"] = "value2"
+        input = Lutaml::Model::MappingHash.new
+        input["key1"] = child1
+        input["key2"] = child2
+        expected = {
           "key1" => { "other" => "value1" },
           "key2" => { "other" => "value2" },
         }
+        expect(described_class.cast(input)).to eq(expected)
       end
 
-      it "filters out text keys from nested hashes" do
-        expect(described_class.cast(input)).to eq(expected_hash)
+      it "preserves text keys in nested plain hashes" do
+        input = {
+          "key1" => { "text" => "content1", "other" => "value1" },
+          "key2" => { "text" => "content2", "other" => "value2" },
+        }
+        expect(described_class.cast(input)).to eq(input)
       end
     end
 

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.132
+  version: 0.8.134
 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