lutaml-model 0.8.44 → 0.8.46

data/lib/lutaml/model.rb

@@ -138,6 +138,8 @@ module Lutaml
     autoload :ElementCountOutOfRangeError,
              "#{__dir__}/model/error/element_count_out_of_range_error"
     autoload :ValidationError, "#{__dir__}/model/error/validation_error"
+    autoload :UnknownDiscriminatorError,
+             "#{__dir__}/model/error/unknown_discriminator_error"
     autoload :TypeNotEnabledError,
              "#{__dir__}/model/error/type_not_enabled_error"
     autoload :TypeError, "#{__dir__}/model/error/type_error"

data/lib/lutaml/xml/mapping.rb

@@ -528,6 +528,7 @@ module Lutaml
       transform: {},
       value_map: {},
       when_attribute: {},
+      unmatched: :drop,
       form: nil,
       documentation: nil,
       xsd_type: (xsd_type_provided = false
@@ -539,6 +540,7 @@ module Lutaml
         )
 
         validate_when_attribute!(when_attribute) unless when_attribute.empty?
+        validate_unmatched!(unmatched, when_attribute)
 
         # Warn if prefix parameter is provided
         if prefix_provided != false
@@ -588,6 +590,7 @@ module Lutaml
           documentation: documentation,
           raw: raw,
           when_attribute: when_attribute,
+          unmatched: unmatched,
         )
         # Store rules with the same element name in an array to support
         # multiple mapping rules for the same element name with different target types
@@ -611,20 +614,6 @@ module Lutaml
         end
       end
 
-      # lutaml-model#88: attribute-value discriminator. Keys are wire
-      # attribute names, values the expected string value.
-      def validate_when_attribute!(when_attribute)
-        when_attribute.each do |k, v|
-          next if (k.is_a?(::String) || k.is_a?(::Symbol)) &&
-            (v.is_a?(::String) || v.is_a?(::Symbol))
-
-          raise Lutaml::Model::IncorrectMappingArgumentsError,
-                "when_attribute expects string/symbol attribute names " \
-                "mapped to string/symbol values, got " \
-                "#{k.inspect} => #{v.inspect}"
-        end
-      end
-
       def map_attribute(
         name,
       to: nil,

data/lib/lutaml/xml/mapping_rule.rb

@@ -11,7 +11,8 @@ module Lutaml
                   :delimiter,
                   :form,
                   :documentation,
-                  :raw
+                  :raw,
+                  :unmatched
 
       # Writers for deep_dup (preserves exact object references)
       attr_accessor :namespace, :prefix, :namespace_class
@@ -38,6 +39,7 @@ module Lutaml
       transform: {},
       value_map: {},
       when_attribute: {},
+      unmatched: :drop,
       as_list: nil,
       delimiter: nil,
       form: nil,
@@ -66,6 +68,9 @@ module Lutaml
         # Store original namespace parameter to preserve :inherit symbol
         @namespace_param = namespace
 
+        # lutaml-model#88: policy for occurrences claimed by no rule
+        @unmatched = unmatched
+
         # Normalize namespace to XmlNamespace class
         @namespace_class = normalize_namespace(namespace)
         @namespace = @namespace_class == :blank ? nil : @namespace_class&.uri
@@ -273,6 +278,7 @@ module Lutaml
           documentation: @documentation,
           raw: @raw,
           when_attribute: when_attribute,
+          unmatched: @unmatched,
         ).tap do |dup_rule|
           # Manually preserve the exact @namespace_class object to avoid
           # recreating anonymous classes (which would have different object_ids)

data/lib/lutaml/xml/model_transform.rb

@@ -859,6 +859,35 @@ _effective_register)
         cache[type_class] = type_class.mappings_for(:xml)&.namespace_class
       end
 
+      # lutaml-model#88: fail closed for `unmatched: :raise`. An
+      # occurrence no rule on the wire name claims — no discriminator
+      # match, no plain sibling — is exactly the data the default policy
+      # silently drops.
+      def check_unmatched_discriminators!(children, rule, rule_names, session)
+        plain_names = session.plain_element_rule_names
+        return if rule_names.any? { |name| plain_names[name] }
+
+        group = rule_names.filter_map do |name|
+          session.when_attribute_siblings_by_name[name]
+        end.flatten
+        tested = group.flat_map { |sibling| sibling.when_attribute.keys }
+          .uniq.map(&:to_s)
+        children.each do |child|
+          next if group.any? { |sibling| sibling.matches_when_attribute?(child) }
+
+          values = tested.filter_map do |name|
+            value = child.find_attribute_value(name)
+            "#{name}=#{value.inspect}" if value
+          end
+          raise ::Lutaml::Model::UnknownDiscriminatorError,
+                "Element <#{rule.name}> (#{values.join(', ')}) is claimed by " \
+                "no rule: it matches no when_attribute discriminator and no " \
+                "plain rule shares the name. Cover the value, add a plain " \
+                "rule, or opt out with unmatched: :drop"
+        end
+        nil
+      end
+
       def value_for_rule(session, rule, options, cached_attr = nil,
                          extra_rule_names = nil)
         doc = session.doc
@@ -1058,6 +1087,9 @@ _effective_register)
         # no discriminator claimed — so each occurrence is captured
         # exactly once, mirroring ordered-serialization routing.
         if rule.when_attribute?
+          if rule.unmatched == :raise
+            check_unmatched_discriminators!(children, rule, rule_names, session)
+          end
           children = children.select do |child|
             rule.matches_when_attribute?(child)
           end

data/lib/lutaml/xml/parse_session.rb

@@ -66,27 +66,49 @@ module Lutaml
       end
 
       # lutaml-model#88: element wire names partitioned by `when_attribute`
-      # rules, as name -> discriminator rules. A plain rule on a
-      # partitioned name captures only occurrences no discriminator
-      # claimed — the mirror of ordered-serialization routing, so each
-      # occurrence is captured exactly once instead of double-captured by
-      # the plain rule and its discriminator sibling. Empty unless the
-      # mapping uses when_attribute at all; non-Serialize custom models
-      # have no mappings to partition.
-      def when_attribute_siblings_by_name
-        @when_attribute_siblings_by_name ||=
+      # rules. One pass builds two views over the mapping's element rules:
+      #
+      # - name -> discriminator rules. A plain rule on a partitioned name
+      #   captures only occurrences no discriminator claimed — the mirror
+      #   of ordered-serialization routing, so each occurrence is captured
+      #   exactly once instead of double-captured by the plain rule and
+      #   its discriminator sibling.
+      # - name -> true when a plain element rule also holds the name.
+      #   Everything on the name is then claimed, so `unmatched: :raise`
+      #   never fires.
+      #
+      # Empty unless the mapping uses when_attribute at all; non-Serialize
+      # custom models have no mappings to partition.
+      def when_attribute_partition
+        @when_attribute_partition ||=
           if instance_is_serialize && (mapping = xml_mapping)
-            mapping.mappings.each_with_object({}) do |rule, index|
-              pairs = rule.when_attribute
-              next if pairs.nil? || pairs.empty?
+            siblings = {}
+            plain_names = {}
+            mapping.mappings.each do |rule|
+              next if rule.attribute? || rule.content_mapping? ||
+                rule.raw_mapping? || rule.cdata
 
-              (index[rule.name.to_s] ||= []) << rule
+              pairs = rule.when_attribute
+              if pairs && !pairs.empty?
+                (siblings[rule.name.to_s] ||= []) << rule
+              else
+                plain_names[rule.name.to_s] = true
+              end
             end
+            [siblings, plain_names]
           else
-            {}
+            [{}, {}]
           end
       end
 
+      def when_attribute_siblings_by_name
+        when_attribute_partition[0]
+      end
+
+      def plain_element_rule_names
+        when_attribute_partition[1]
+      end
+
       def model_class
         @model_class ||= instance.class
       end

data/spec/lutaml/key_value/when_attribute_spec.rb

@@ -0,0 +1,348 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# lutaml-model#88: `when_attribute` partitioning for key-value formats.
+# The discriminator is an object key: items of the array at a shared wire
+# key are claimed by the rule whose pairs their key values satisfy.
+# Serialization merges every rule's items back under the one key, each
+# item stamped with its rule's discriminator pairs.
+class KvWhenComponent < Lutaml::Model::Serializable
+  attribute :text, :string
+
+  json do
+    map "text", to: :text
+  end
+
+  yaml do
+    map "text", to: :text
+  end
+
+  toml do
+    map "text", to: :text
+  end
+
+  hsh do
+    map "text", to: :text
+  end
+end
+
+class KvWhenRequirement < Lutaml::Model::Serializable
+  attribute :guidance, KvWhenComponent, collection: true
+  attribute :purpose, KvWhenComponent, collection: true
+
+  json do
+    map "component", to: :guidance,
+                     when_attribute: { "type" => "guidance" }
+    map "component", to: :purpose,
+                     when_attribute: { "type" => "purpose" }
+  end
+
+  yaml do
+    map "component", to: :guidance,
+                     when_attribute: { "type" => "guidance" }
+    map "component", to: :purpose,
+                     when_attribute: { "type" => "purpose" }
+  end
+
+  hsh do
+    map "component", to: :guidance,
+                     when_attribute: { "type" => "guidance" }
+    map "component", to: :purpose,
+                     when_attribute: { "type" => "purpose" }
+  end
+end
+
+RSpec.describe "when_attribute for key-value formats" do
+  before do
+    stub_const("KvWhen::Component", KvWhenComponent)
+    stub_const("KvWhen::Requirement", KvWhenRequirement)
+  end
+
+  let(:payload) do
+    {
+      "component" => [
+        { "type" => "guidance", "text" => "g1" },
+        { "type" => "purpose", "text" => "p1" },
+        { "type" => "guidance", "text" => "g2" },
+      ],
+    }
+  end
+
+  it "partitions json by the discriminator key" do
+    req = KvWhenRequirement.from_json(payload.to_json)
+
+    expect(req.guidance.map(&:text)).to eq(%w[g1 g2])
+    expect(req.purpose.map(&:text)).to eq(["p1"])
+  end
+
+  it "partitions yaml arrays of mappings" do
+    req = KvWhenRequirement.from_yaml(payload.to_yaml)
+
+    expect(req.guidance.map(&:text)).to eq(%w[g1 g2])
+    expect(req.purpose.map(&:text)).to eq(["p1"])
+  end
+
+  it "partitions hashes passed directly with symbol keys" do
+    req = KvWhenRequirement.from_hash(
+      component: [
+        { type: "guidance", text: "g1" },
+        { type: "purpose", text: "p1" },
+      ],
+    )
+
+    expect(req.guidance.map(&:text)).to eq(["g1"])
+    expect(req.purpose.map(&:text)).to eq(["p1"])
+  end
+
+  it "keeps a single object occurrence as one item" do
+    req = KvWhenRequirement.from_hash(
+      "component" => { "type" => "purpose", "text" => "p1" },
+    )
+
+    expect(req.purpose.map(&:text)).to eq(["p1"])
+    expect(req.guidance).to be_empty
+  end
+
+  it "serializes one merged array with the discriminators stamped" do
+    req = KvWhenRequirement.from_json(payload.to_json)
+    out = req.to_json
+
+    items = JSON.parse(out)["component"]
+    expect(items).to eq([
+                          { "type" => "guidance", "text" => "g1" },
+                          { "type" => "guidance", "text" => "g2" },
+                          { "type" => "purpose", "text" => "p1" },
+                        ])
+  end
+
+  it "round-trips through yaml" do
+    req = KvWhenRequirement.from_yaml(payload.to_yaml)
+    again = KvWhenRequirement.from_yaml(req.to_yaml)
+
+    expect(again.guidance.map(&:text)).to eq(%w[g1 g2])
+    expect(again.purpose.map(&:text)).to eq(["p1"])
+  end
+
+  it "does not stamp over a key the item's own mapping writes" do
+    holder = Class.new(Lutaml::Model::Serializable) do
+      attribute :items, KvWhenComponent, collection: true
+
+      json do
+        map "component", to: :items,
+                         when_attribute: { "type" => "guidance" }
+      end
+
+      hsh do
+        map "component", to: :items,
+                         when_attribute: { "type" => "guidance" }
+      end
+    end
+    stub_const("KvWhen::Holder", holder)
+
+    out = holder.from_hash(
+      "component" => [{ "type" => "guidance", "text" => "g" }],
+    ).to_json
+    expect(JSON.parse(out)["component"]).to eq(
+      [{ "type" => "guidance", "text" => "g" }],
+    )
+  end
+
+  describe "plain rule complement" do
+    let(:holder) do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :special, KvWhenComponent, collection: true
+        attribute :plain, KvWhenComponent, collection: true
+
+        json do
+          map "item", to: :special, when_attribute: { "kind" => "special" }
+          map "item", to: :plain
+        end
+
+        hsh do
+          map "item", to: :special, when_attribute: { "kind" => "special" }
+          map "item", to: :plain
+        end
+      end
+    end
+
+    it "captures occurrences no discriminator claimed exactly once" do
+      stub_const("KvWhen::Both", holder)
+      doc = holder.from_hash(
+        "item" => [
+          { "kind" => "special", "text" => "b" },
+          { "text" => "a" },
+          { "kind" => "other", "text" => "x" },
+        ],
+      )
+
+      expect(doc.special.map(&:text)).to eq(["b"])
+      expect(doc.plain.map(&:text)).to eq(%w[a x])
+    end
+
+    it "merges plain and stamped items into the one key" do
+      stub_const("KvWhen::Both", holder)
+      doc = holder.from_hash(
+        "item" => [
+          { "kind" => "special", "text" => "b" },
+          { "text" => "a" },
+        ],
+      )
+      items = JSON.parse(doc.to_json)["item"]
+
+      expect(items).to eq([
+                            { "kind" => "special", "text" => "b" },
+                            { "text" => "a" },
+                          ])
+    end
+  end
+
+  describe "unmatched policy" do
+    let(:strict) do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :guidance, KvWhenComponent, collection: true
+
+        json do
+          map "component", to: :guidance,
+                           when_attribute: { "type" => "guidance" },
+                           unmatched: :raise
+        end
+      end
+    end
+
+    it "raises on an unclaimed discriminator value" do
+      stub_const("KvWhen::Strict", strict)
+
+      expect do
+        strict.from_json({ "component" => [
+          { "type" => "guidance", "text" => "g" },
+          { "type" => "nope", "text" => "x" },
+        ] }.to_json)
+      end.to raise_error(Lutaml::Model::UnknownDiscriminatorError, /type="nope"/)
+    end
+
+    it "raises on an item without the discriminator key" do
+      stub_const("KvWhen::Strict", strict)
+
+      expect do
+        strict.from_json({ "component" => [{ "text" => "x" }] }.to_json)
+      end.to raise_error(Lutaml::Model::UnknownDiscriminatorError, /<component>/)
+    end
+
+    it "drops unclaimed occurrences by default" do
+      lenient = Class.new(Lutaml::Model::Serializable) do
+        attribute :guidance, KvWhenComponent, collection: true
+
+        json do
+          map "component", to: :guidance,
+                           when_attribute: { "type" => "guidance" }
+        end
+      end
+      stub_const("KvWhen::Lenient", lenient)
+
+      doc = lenient.from_json({ "component" => [
+        { "type" => "guidance", "text" => "g" },
+        { "type" => "other", "text" => "x" },
+      ] }.to_json)
+      expect(doc.guidance.map(&:text)).to eq(["g"])
+    end
+  end
+
+  describe "toml arrays of tables" do
+    let(:toml_holder) do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :guidance, KvWhenComponent, collection: true
+        attribute :purpose, KvWhenComponent, collection: true
+
+        toml do
+          map "component", to: :guidance,
+                           when_attribute: { "type" => "guidance" }
+          map "component", to: :purpose,
+                           when_attribute: { "type" => "purpose" }
+        end
+      end
+    end
+
+    it "partitions and round-trips" do
+      stub_const("KvWhen::TomlHolder", toml_holder)
+      src = <<~TOML
+        [[component]]
+        type = "guidance"
+        text = "g1"
+
+        [[component]]
+        type = "purpose"
+        text = "p1"
+      TOML
+
+      doc = toml_holder.from_toml(src)
+      expect(doc.guidance.map(&:text)).to eq(["g1"])
+      expect(doc.purpose.map(&:text)).to eq(["p1"])
+
+      again = toml_holder.from_toml(doc.to_toml)
+      expect(again.guidance.map(&:text)).to eq(["g1"])
+      expect(again.purpose.map(&:text)).to eq(["p1"])
+    end
+  end
+
+  describe "DSL validation" do
+    it "rejects non-string/symbol pairs" do
+      expect do
+        Class.new(Lutaml::Model::Serializable) do
+          attribute :x, :string
+
+          json do
+            map "x", to: :x, when_attribute: { "type" => 42 }
+          end
+        end
+      end.to raise_error(Lutaml::Model::IncorrectMappingArgumentsError, /when_attribute/)
+    end
+
+    it "rejects unmatched without when_attribute" do
+      expect do
+        Class.new(Lutaml::Model::Serializable) do
+          attribute :x, :string
+
+          json do
+            map "x", to: :x, unmatched: :raise
+          end
+        end
+      end.to raise_error(Lutaml::Model::IncorrectMappingArgumentsError, /when_attribute/)
+    end
+
+    it "rejects unknown policy values" do
+      expect do
+        Class.new(Lutaml::Model::Serializable) do
+          attribute :x, :string
+
+          json do
+            map "x", to: :x, when_attribute: { "type" => "a" },
+                     unmatched: :explode
+          end
+        end
+      end.to raise_error(Lutaml::Model::IncorrectMappingArgumentsError, /unmatched/)
+    end
+
+    it "rejects when_attribute combined with custom methods" do
+      expect do
+        Class.new(Lutaml::Model::Serializable) do
+          attribute :x, :string
+
+          json do
+            map "x", to: :x, when_attribute: { "type" => "a" },
+                     with: { to: :x_to, from: :x_from }
+          end
+        end
+      end.to raise_error(Lutaml::Model::IncorrectMappingArgumentsError, /when_attribute/)
+    end
+
+    it "survives deep_dup of mappings" do
+      rule = KvWhenRequirement.mappings_for(:json).mappings.find do |r|
+        r.to == :guidance
+      end
+
+      expect(rule.when_attribute).to eq("type" => "guidance")
+      expect(rule.deep_dup.when_attribute).to eq("type" => "guidance")
+    end
+  end
+end