lutaml-model 0.8.133 → 0.8.134

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ea94bb734406bacfb047edb9c580a3f224f19c497b4f506440da60d381cd1bf
-  data.tar.gz: 96f7c71f51a0ec8b863eec77b894ec611ff3a4e8b59354ec9b477e6470258852
+  metadata.gz: 250473959d5b49e40ab480a2acf1e708d2cac1f8d5b092995be03821bc758122
+  data.tar.gz: 59fc186602fae873d070d23baca950a2330a07abbb251acd16b3a63803877a93
 SHA512:
-  metadata.gz: 4e61d4a02ebb21a794de64a0301a3489b045b8562ce8e1a8f3522b227bea1632882e7e09d1ce6fe18352d41c8fe62d2a5d9652b315dda76a220cbd30fe15f3cf
-  data.tar.gz: 60c206b080775425586980a1f3b484db2280be9e9b73bc365237210f64c90fc3faa80f1f9e9a42e94259a9a83ba1edab1ceecc25bb804147ecd3e31ead97c15d
+  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/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.133"
+    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/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.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