lutaml-model 0.8.112 → 0.8.114

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f1d5fc3ccd267d7c8c8f4a7117db2f01b1a81da024724128402ca058584526b
-  data.tar.gz: 0c5fa1399c3e9df481ee09480f1851493544c0c26cf1e0f8851c381dec5dfa64
+  metadata.gz: 381cba1519b14ff18965d44164e7d75e4564ac92c803815dad95277b7076ef70
+  data.tar.gz: acd3466cbc30ed27ce60ce62b181732ab957abde427da1e609003ced88c47a67
 SHA512:
-  metadata.gz: 4809033fde8d06502a1cde12873b1d3214b2f9799c56e9e5e8d390979e0c370332a69d072f780d903349f6115028fb9c35fc0abbc1b84290d380a8ec9e0ed20c
-  data.tar.gz: 7756798eb9c1484c509eeddef382a1566dbfbe5fb00dbc133f1d0912589cbd44e6fa539dd5f1ab428de9a37abd2c5a2aa752354df04e299ddd697bfe3ca80e60
+  metadata.gz: 8f48a3c4bc8a0242a714d945aae2aaca68ae6c0a8a87cedb038a1229363545bb41f1a3c24f833db86c89e3468cc216c77536af23385cce37e6ce20f8a2e3b142
+  data.tar.gz: 9ba5616b479da6952fd44284792ce708712ed6576ba90fa11507581aefd344f30ccd22e5887e3200c714feff15e7e8c95742149f49ac2a5618b2d5ea0f0b742a

data/lib/lutaml/key_value/transform.rb

@@ -687,6 +687,10 @@ partition = nil)
         # attribute is not a collection, so this guard defers exactly that case
         # to `.validate` while leaving declared ranges checked at parse. A mapped
         # PORO has no `.validate` to defer into, so it keeps the eager check.
+        # singular_tolerance: :first on the KV lane (#971): collapse an
+        # over-ingested collection before the writer stores it whole.
+        value = value.first if attr.tolerates_singular_overflow?(value)
+
         if attr.collection? || !instance.is_a?(Lutaml::Model::Serialize)
           attr.valid_collection!(value, context)
         end

data/lib/lutaml/key_value/transformation.rb

@@ -1031,6 +1031,16 @@ child_mappings, options)
                               rule.attribute_type < Lutaml::Model::Serialize
                           end
 
+        if is_nested_model && !value.is_a?(Lutaml::Model::Serialize)
+          # The KV mirror of the XML lane's #971 collapse: a tolerated
+          # singular attribute holding an over-assigned collection
+          # serializes its leading value instead of raising.
+          attr = if model_class.respond_to?(:attributes)
+                   model_class.attributes[rule.attribute_name.to_sym]
+                 end
+          value = value.first if attr&.tolerates_singular_overflow?(value)
+        end
+
         if is_nested_model
           # Validate that value matches the expected type
           # There are three valid cases:

data/lib/lutaml/model/attribute.rb

@@ -47,6 +47,7 @@ module Lutaml
         min_length
         max_length
         desc
+        singular_tolerance
       ].freeze
 
       # Per-type-class memo of the custom from_xml/from_json probe used by #cast.
@@ -827,6 +828,17 @@ instance_object = nil)
         end
       end
 
+      # Singular-overflow tolerance (#971): ingest can hand a singular
+      # attribute a collection — relaton's upstream documents carry
+      # multiple <formattedref> elements per bibitem. With
+      # singular_tolerance: :first the leading value is kept instead of
+      # raising CollectionTrueMissingError; the default stays strict.
+      def tolerates_singular_overflow?(value)
+        !collection? && @options[:singular_tolerance] == :first &&
+          collection_instance?(value) &&
+          !value_policy.whole_value?(unresolved_type)
+      end
+
       def valid_collection!(value, caller)
         if collection_instance?(value) && !collection? &&
             !value_policy.whole_value?(unresolved_type)
@@ -1041,6 +1053,12 @@ instance_object = nil)
                "Use map_element \"name\", to: :#{name}, raw: :content instead."
         end
         @validations = @options[:validations]
+        tolerance = @options[:singular_tolerance]
+        unless tolerance.nil? || tolerance == :first
+          raise ArgumentError,
+                "Invalid singular_tolerance: #{tolerance.inspect} for " \
+                "attribute '#{name}'. Supported: :first"
+        end
         set_default_for_collection if collection?
       end
 

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.112"
+    VERSION = "0.8.114"
   end
 end

data/lib/lutaml/xml/model_transform.rb

@@ -479,6 +479,11 @@ module Lutaml
           # violation entirely — check it while there is still someone to tell.
           if !instance_is_serialize && attr && !attr.collection? &&
               !rule.content_mapping?
+            # singular_tolerance: :first collapses an over-ingested
+            # collection to its leading value before the writer sees it
+            # (#971) — the reduced scalar then flows through
+            # deserialize and serializes as a single element.
+            value = value.first if attr.tolerates_singular_overflow?(value)
             attr.valid_collection!(value, context)
           end
           rule.deserialize(instance, value, deserialize_attributes, context,

data/lutaml-model.gemspec

@@ -41,7 +41,7 @@ Gem::Specification.new do |spec|
   # 0.5.84 always passes XML_PARSE_HUGE to libxml2: very large documents
   # parse completely instead of being silently truncated at the 10 MB
   # input-buffer cap (lutaml-model#871).
-  spec.add_dependency "moxml", "~> 0.5.84"
+  spec.add_dependency "moxml", "~> 0.5.139"
   spec.add_dependency "ostruct"
   spec.add_dependency "rubyzip", "~> 3.7"
   spec.add_dependency "thor", "~> 1.4"

data/spec/lutaml/model/singular_tolerance_spec.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# #971: a singular attribute may ask ingest to keep the leading value
+# when the mapper collects more than one element (relaton's upstream
+# bibitems carry multiple <formattedref> elements). Default stays
+# strict: the over-count remains a CollectionTrueMissingError.
+RSpec.describe "singular_tolerance attribute option" do
+  let(:item_class) do
+    Class.new(Lutaml::Model::Serializable) do
+      attribute :content, :string
+    end
+  end
+
+  before do
+    stub_const("ToleranceItem", item_class)
+  end
+
+  describe "option validation" do
+    it "accepts :first" do
+      expect do
+        Lutaml::Model::Attribute.new(:ref, "ToleranceItem",
+                                     singular_tolerance: :first)
+      end.not_to raise_error
+    end
+
+    it "accepts omission (strict default)" do
+      expect do
+        Lutaml::Model::Attribute.new(:ref, "ToleranceItem")
+      end.not_to raise_error
+    end
+
+    it "rejects unsupported tolerances" do
+      expect do
+        Lutaml::Model::Attribute.new(:ref, "ToleranceItem",
+                                     singular_tolerance: :last)
+      end.to raise_error(ArgumentError, /singular_tolerance: :last/)
+    end
+  end
+
+  describe "#tolerates_singular_overflow?" do
+    let(:tolerant) do
+      Lutaml::Model::Attribute.new(:ref, "ToleranceItem",
+                                   singular_tolerance: :first)
+    end
+
+    let(:strict) { Lutaml::Model::Attribute.new(:ref, "ToleranceItem") }
+
+    let(:collection_attr) do
+      Lutaml::Model::Attribute.new(:refs, "ToleranceItem",
+                                   collection: true,
+                                   singular_tolerance: :first)
+    end
+
+    it "is true for an over-ingested collection on a tolerant singular" do
+      expect(tolerant.tolerates_singular_overflow?([1, 2])).to be(true)
+    end
+
+    it "is false without the option" do
+      expect(strict.tolerates_singular_overflow?([1, 2])).to be(false)
+    end
+
+    it "is false for a scalar on a tolerant singular" do
+      expect(tolerant.tolerates_singular_overflow?(1)).to be(false)
+    end
+
+    it "is false for a collection attribute — the option does not apply" do
+      expect(collection_attr.tolerates_singular_overflow?([1, 2])).to be(false)
+    end
+  end
+
+  describe "strict default" do
+    it "still raises CollectionTrueMissingError on over-ingest" do
+      attr = Lutaml::Model::Attribute.new(:ref, "ToleranceItem")
+
+      expect do
+        attr.valid_collection!([item_class.new, item_class.new], String)
+      end.to raise_error(Lutaml::Model::CollectionTrueMissingError)
+    end
+  end
+
+  describe "tolerant ingest" do
+    it "lets valid_collection! pass after the transform reduces to first" do
+      attr = Lutaml::Model::Attribute.new(:ref, "ToleranceItem",
+                                          singular_tolerance: :first)
+      value = [item_class.new, item_class.new]
+
+      reduced = value.first if attr.tolerates_singular_overflow?(value)
+      expect(attr.valid_collection!(reduced, String)).to be(true)
+      expect(reduced).to eq(value.first)
+    end
+  end
+
+  describe "on the KeyValue lane" do
+    let(:marked_class) do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :content, :string
+
+        key_value do
+          map "content", to: :content
+        end
+      end
+    end
+
+    let(:relation_class) do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :rel_type, :string
+        attribute :description, "ToleranceMarked", singular_tolerance: :first
+
+        key_value do
+          map "type", to: :rel_type
+          map "description", to: :description
+        end
+      end
+    end
+
+    before do
+      stub_const("ToleranceMarked", marked_class)
+      stub_const("ToleranceRelation", relation_class)
+    end
+
+    it "keeps the leading value on ingest instead of the whole array" do
+      model = ToleranceRelation.from_yaml(
+        "---\ntype: cites\ndescription:\n  - content: First\n  - content: Second\n",
+      )
+
+      expect(model.description).to be_a(ToleranceMarked)
+      expect(model.description.content).to eq("First")
+    end
+
+    it "round-trips the collapsed singular through to_yaml" do
+      model = ToleranceRelation.from_yaml(
+        "---\ntype: cites\ndescription:\n  - content: First\n  - content: Second\n",
+      )
+
+      yaml = model.to_yaml
+      expect(yaml).to include("First")
+      expect(yaml).not_to include("Second")
+      expect(ToleranceRelation.from_yaml(yaml).description.content).to eq("First")
+    end
+
+    it "collapses an over-assigned collection at serialization" do
+      model = ToleranceRelation.new(
+        rel_type: "cites",
+        description: [ToleranceMarked.new(content: "One"),
+                      ToleranceMarked.new(content: "Two")],
+      )
+
+      yaml = model.to_yaml
+      expect(yaml).to include("One")
+      expect(yaml).not_to include("Two")
+    end
+  end
+end
+
+# The KV mirror of the XML-lane cases: the YAML lane never consulted
+# the tolerance — ingest stored the whole array and re-serialization
+# raised the mapped-PORO type check.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.112
+  version: 0.8.114
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-17 00:00:00.000000000 Z
+date: 2026-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -92,14 +92,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.5.84
+        version: 0.5.139
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.5.84
+        version: 0.5.139
 - !ruby/object:Gem::Dependency
   name: ostruct
   requirement: !ruby/object:Gem::Requirement
@@ -1824,6 +1824,7 @@ files:
 - spec/lutaml/model/serialize_perf_guard_spec.rb
 - spec/lutaml/model/services/transformer_spec.rb
 - spec/lutaml/model/simple_model_spec.rb
+- spec/lutaml/model/singular_tolerance_spec.rb
 - spec/lutaml/model/store_spec.rb
 - spec/lutaml/model/toml_adapter_spec.rb
 - spec/lutaml/model/toml_spec.rb