lutaml-model 0.8.112 → 0.8.113

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f1d5fc3ccd267d7c8c8f4a7117db2f01b1a81da024724128402ca058584526b
-  data.tar.gz: 0c5fa1399c3e9df481ee09480f1851493544c0c26cf1e0f8851c381dec5dfa64
+  metadata.gz: be72639a2ee2fd3c23219f19141d43386c4126fbef9fa79fdff322f90bb58660
+  data.tar.gz: 8c88a30cdda640eba02043ba87859a3cda864dcc23addf6a60aeccda63600dff
 SHA512:
-  metadata.gz: 4809033fde8d06502a1cde12873b1d3214b2f9799c56e9e5e8d390979e0c370332a69d072f780d903349f6115028fb9c35fc0abbc1b84290d380a8ec9e0ed20c
-  data.tar.gz: 7756798eb9c1484c509eeddef382a1566dbfbe5fb00dbc133f1d0912589cbd44e6fa539dd5f1ab428de9a37abd2c5a2aa752354df04e299ddd697bfe3ca80e60
+  metadata.gz: c5bfd563e53d7664d038da01d677152f3143c510cb1fa2cc56e13d20d5f6f9009251c618091258d58f7b25c45b70ab7c53e6a1fdafdb3a91213da871e3fde875
+  data.tar.gz: a29144bc6c8cc8a3cf466e911b766df00718db916ddd3fc7127de00679f009ebe322407b9b74b509bf8fd4362005c7d85ce6076497d4b1676ab06648ab2a8213

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.113"
   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/spec/lutaml/model/singular_tolerance_spec.rb

@@ -0,0 +1,94 @@
+# 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
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.112
+  version: 0.8.113
 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
@@ -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