lutaml-model 0.8.45 → 0.8.47

data/lib/lutaml/model/mapping/mapping.rb

@@ -106,6 +106,77 @@ module Lutaml
 
       attr_accessor :importable_mappings
 
+      # lutaml-model#88: attribute-value discriminator. Keys are wire
+      # names (an XML attribute, or an object key in key-value formats),
+      # values the expected string value. Shared by the XML and KV DSLs.
+      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
+
+      # lutaml-model#88: what a parse does with an occurrence that no
+      # rule on the wire name claims — :drop it (default) or :raise
+      # UnknownDiscriminatorError. Only meaningful on discriminator rules.
+      def validate_unmatched!(unmatched, when_attribute)
+        unless %i[drop raise].include?(unmatched)
+          raise Lutaml::Model::IncorrectMappingArgumentsError,
+                "unmatched expects :drop or :raise, got #{unmatched.inspect}"
+        end
+
+        return unless when_attribute.empty? && unmatched != :drop
+
+        raise Lutaml::Model::IncorrectMappingArgumentsError,
+              "unmatched only applies to rules declared with when_attribute"
+      end
+
+      # lutaml-model#88: grouped discriminator form.
+      # `when_attribute: "type"` names the discriminator key; `to:` maps
+      # each wire value to its target attribute. Validates the shape and
+      # returns the group pairs — the DSL then expands one rule per
+      # value, so the compiled rules are identical to the per-rule form.
+      def when_attribute_group(when_attribute, to)
+        if when_attribute.to_s.empty?
+          raise Lutaml::Model::IncorrectMappingArgumentsError,
+                "when_attribute group key cannot be empty"
+        end
+        unless to.is_a?(::Hash) && !to.empty?
+          raise Lutaml::Model::IncorrectMappingArgumentsError,
+                "when_attribute: #{when_attribute.inspect} is the grouped " \
+                "form and requires to: { value => attribute }, got " \
+                "to: #{to.inspect}"
+        end
+
+        to.each do |value, target|
+          next if (value.is_a?(::String) || value.is_a?(::Symbol)) &&
+            (target.is_a?(::String) || target.is_a?(::Symbol))
+
+          raise Lutaml::Model::IncorrectMappingArgumentsError,
+                "when_attribute group expects string/symbol values mapped " \
+                "to string/symbol attribute names, got " \
+                "#{value.inspect} => #{target.inspect}"
+        end
+        to
+      end
+
+      # The per-rule `{ name => value }` form maps ONE attribute; a Hash
+      # `to:` only makes sense with the grouped form.
+      def reject_ambiguous_when_attribute!(when_attribute, to)
+        return unless when_attribute.is_a?(::Hash) && !when_attribute.empty? &&
+          to.is_a?(::Hash)
+
+        raise Lutaml::Model::IncorrectMappingArgumentsError,
+              "to: must name a single attribute when when_attribute is the " \
+              "per-rule { name => value } form; the grouped form is " \
+              'when_attribute: "key", to: { value => attribute }'
+      end
+
       def register(register_id = nil)
         register_id ||= Lutaml::Model::Config.default_register
         Lutaml::Model::GlobalRegister.lookup(register_id)

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.45"
+    VERSION = "0.8.47"
   end
 end

data/lib/lutaml/xml/mapping.rb

@@ -539,6 +539,48 @@ module Lutaml
           name, to, with, render_nil, render_empty, type: TYPES[:element]
         )
 
+        # lutaml-model#88: grouped form — `when_attribute: "type"` plus
+        # `to: { value => attribute }` expands to one rule per value at
+        # DSL time, so the compiled rules are identical to the per-rule
+        # form and nothing downstream changes.
+        if when_attribute.is_a?(::String) || when_attribute.is_a?(::Symbol)
+          # These locals are `false` when their kwarg default ran and
+          # nil when the caller passed the kwarg explicitly (planned
+          # locals read as nil, so defined? is useless here).
+          if namespace_set.nil? || prefix_provided.nil? ||
+              xsd_type_provided.nil?
+            raise Lutaml::Model::IncorrectMappingArgumentsError,
+                  "namespace/prefix/xsd_type are not supported in the " \
+                  "grouped when_attribute form; declare rules individually"
+          end
+
+          when_attribute_group(when_attribute, to).each do |value, target|
+            map_element(
+              name,
+              to: target,
+              render_nil: render_nil,
+              render_default: render_default,
+              render_empty: render_empty,
+              treat_nil: treat_nil,
+              treat_empty: treat_empty,
+              treat_omitted: treat_omitted,
+              with: with,
+              delegate: delegate,
+              cdata: cdata,
+              polymorphic: polymorphic,
+              transform: transform,
+              value_map: value_map,
+              when_attribute: { when_attribute.to_s => value.to_s },
+              unmatched: unmatched,
+              form: form,
+              documentation: documentation,
+              raw: raw,
+            )
+          end
+          return
+        end
+        reject_ambiguous_when_attribute!(when_attribute, to)
+
         validate_when_attribute!(when_attribute) unless when_attribute.empty?
         validate_unmatched!(unmatched, when_attribute)
 
@@ -614,35 +656,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
-
-      # lutaml-model#88: what a parse does with an occurrence that no
-      # rule on the wire name claims — :drop it (default) or :raise
-      # UnknownDiscriminatorError. Only meaningful on discriminator rules.
-      def validate_unmatched!(unmatched, when_attribute)
-        unless %i[drop raise].include?(unmatched)
-          raise Lutaml::Model::IncorrectMappingArgumentsError,
-                "unmatched expects :drop or :raise, got #{unmatched.inspect}"
-        end
-
-        return unless when_attribute.empty? && unmatched != :drop
-
-        raise Lutaml::Model::IncorrectMappingArgumentsError,
-              "unmatched only applies to rules declared with when_attribute"
-      end
-
       def map_attribute(
         name,
       to: nil,

data/spec/lutaml/key_value/when_attribute_spec.rb

@@ -0,0 +1,428 @@
+# 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 "grouped form" do
+    let(:grouped) do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :guidance, KvWhenComponent, collection: true
+        attribute :purpose, KvWhenComponent, collection: true
+
+        json do
+          map "component", when_attribute: "type",
+                           to: { guidance: :guidance, purpose: :purpose },
+                           unmatched: :raise
+        end
+
+        hsh do
+          map "component", when_attribute: "type",
+                           to: { guidance: :guidance, purpose: :purpose }
+        end
+      end
+    end
+
+    it "expands to one rule per value with identical behavior" do
+      stub_const("KvWhen::Grouped", grouped)
+      req = grouped.from_json(payload.to_json)
+
+      expect(req.guidance.map(&:text)).to eq(%w[g1 g2])
+      expect(req.purpose.map(&:text)).to eq(["p1"])
+      expect(JSON.parse(req.to_json)["component"]).to eq([
+                                                           { "type" => "guidance", "text" => "g1" },
+                                                           { "type" => "guidance", "text" => "g2" },
+                                                           { "type" => "purpose", "text" => "p1" },
+                                                         ])
+
+      rules = grouped.mappings_for(:json).mappings.select { |r| r.name == "component" }
+      expect(rules.map(&:when_attribute)).to eq(
+        [{ "type" => "guidance" }, { "type" => "purpose" }],
+      )
+    end
+
+    it "works through the hash format" do
+      stub_const("KvWhen::Grouped", grouped)
+      req = grouped.from_hash(
+        "component" => [{ type: "purpose", text: "p1" }],
+      )
+
+      expect(req.purpose.map(&:text)).to eq(["p1"])
+      expect(req.guidance).to be_empty
+    end
+
+    it "forwards the unmatched policy to every rule" do
+      stub_const("KvWhen::Grouped", grouped)
+
+      expect do
+        grouped.from_json({ "component" => [{ "type" => "nope" }] }.to_json)
+      end.to raise_error(Lutaml::Model::UnknownDiscriminatorError, /type="nope"/)
+    end
+
+    it "rejects the grouped form without a to: map" do
+      expect do
+        Class.new(Lutaml::Model::Serializable) do
+          attribute :x, :string
+
+          json do
+            map "x", to: :x, when_attribute: "type"
+          end
+        end
+      end.to raise_error(Lutaml::Model::IncorrectMappingArgumentsError, /to:/)
+    end
+
+    it "rejects a Hash to: with the per-rule form" do
+      expect do
+        Class.new(Lutaml::Model::Serializable) do
+          attribute :x, :string
+
+          json do
+            map "x", when_attribute: { "type" => "a" }, to: { "a" => :x }
+          end
+        end
+      end.to raise_error(Lutaml::Model::IncorrectMappingArgumentsError, /single attribute/)
+    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

data/spec/lutaml/xml/when_attribute_spec.rb

@@ -131,6 +131,99 @@ RSpec.describe "when_attribute discriminator mappings" do
     end.to raise_error(ArgumentError)
   end
 
+  describe "grouped form" do
+    let(:grouped) do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :guidance, WhenAttrComponent, collection: true
+        attribute :purpose, WhenAttrComponent, collection: true
+
+        xml do
+          element "requirement"
+          map_element "component", when_attribute: "type",
+                                   to: { "guidance" => :guidance,
+                                         "purpose" => :purpose },
+                                   unmatched: :raise
+        end
+      end
+    end
+
+    let(:grouped_xml) do
+      <<~XML
+        <requirement>
+          <component type="guidance"><text>g1</text></component>
+          <component type="purpose"><text>p1</text></component>
+          <component type="guidance"><text>g2</text></component>
+        </requirement>
+      XML
+    end
+
+    it "expands to one rule per value with identical behavior" do
+      stub_const("WhenAttr::Grouped", grouped)
+      req = grouped.from_xml(grouped_xml)
+
+      expect(req.guidance.map(&:text)).to eq(%w[g1 g2])
+      expect(req.purpose.map(&:text)).to eq(["p1"])
+      expect(req.to_xml).to include('type="guidance"')
+
+      rules = grouped.mappings_for(:xml).mappings.select { |r| r.name == "component" }
+      expect(rules.map(&:when_attribute)).to eq(
+        [{ "type" => "guidance" }, { "type" => "purpose" }],
+      )
+    end
+
+    it "forwards the unmatched policy to every rule" do
+      stub_const("WhenAttr::Grouped", grouped)
+
+      expect do
+        grouped.from_xml(
+          '<requirement><component type="other"><text>x</text></component></requirement>',
+        )
+      end.to raise_error(Lutaml::Model::UnknownDiscriminatorError, /type="other"/)
+    end
+
+    it "rejects the grouped form without a to: map" do
+      expect do
+        Class.new(Lutaml::Model::Serializable) do
+          attribute :x, :string
+
+          xml do
+            element "x"
+            map_element "x", to: :x, when_attribute: "type"
+          end
+        end
+      end.to raise_error(Lutaml::Model::IncorrectMappingArgumentsError, /to:/)
+    end
+
+    it "rejects a Hash to: with the per-rule form" do
+      expect do
+        Class.new(Lutaml::Model::Serializable) do
+          attribute :x, :string
+
+          xml do
+            element "x"
+            map_element "x", when_attribute: { "type" => "a" },
+                             to: { "a" => :x }
+          end
+        end
+      end.to raise_error(Lutaml::Model::IncorrectMappingArgumentsError, /single attribute/)
+    end
+
+    it "rejects namespace in the grouped form" do
+      expect do
+        Class.new(Lutaml::Model::Serializable) do
+          attribute :x, :string
+
+          xml do
+            element "x"
+            map_element "x", when_attribute: "type",
+                             to: { "a" => :x },
+                             namespace: "https://example.com"
+          end
+        end
+      end.to raise_error(Lutaml::Model::IncorrectMappingArgumentsError, /grouped/)
+    end
+  end
+
   # Orthogonality guard: `when_attribute` partitions occurrences across
   # attributes; `polymorphic` dispatches the class of each hydrated item.
   # Different axes over the same discriminator concept — they compose on