lutaml-model 0.8.31 → 0.8.32

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ffdb7bcf72a5a1f4b3339ed331fe96def70246dd36010d23a469e4d27c7f103
-  data.tar.gz: edb32bba950336b77f2257383aec513126d0bdfb53d6fefa7f5eecbf5fe48f74
+  metadata.gz: 0a0c1ee735ac6b12da331e1f43dc6617d05cfe18534dc5255aaba0c789ee601e
+  data.tar.gz: bde4936c85167bcec7a4618cd8e91c9c4cf65d2feb97b0d94c78bf368f085248
 SHA512:
-  metadata.gz: 489d6825726abe7fb758d544938a679c652e1a0eeb5699757eea57884197b4bd4890cda632231772226ac794ec91f5eac3fc21988594c1dba3c1151a1fe33dac
-  data.tar.gz: 782cba0c296ffa16381f1f36c5614ca7536e3c7a4e628cef77f71d27a1acf37eada825de229d186ca76115149970eb7a110d04a6a5177d1331132f5f6ba8db10
+  metadata.gz: 773ec772915ec1fd0645d68fa2e62c50bea3af147b19c67c22e5bd16cf1f6dec2a00bc1ff1945e612a7a6f5d22ce404d3e9687fead480d54390a847908e6d804
+  data.tar.gz: 318c31871e7bbb83bd1bea6547f3dbeda4e1768da9d44f0e85c7434bd8db15ade859bdf9a909771126b33a85e345bc1e803a93eacdec2e557a51d39bf0e6f8cb

data/README.adoc

@@ -4519,8 +4519,6 @@ end
 
 === Nested collections
 
-TODO: This case needs to be fixed.
-
 Collections can be nested within other models and define their own serialization
 rules.
 
@@ -4533,38 +4531,42 @@ Data:
 
 [source,xml]
 ----
-<titles>
-  <title-group>
-    <artifact>
-      <content>Title One</content>
-    </artifact>
-    <artifact>
-      <content>Title Two</content>
-    </artifact>
-    <artifact>
-      <content>Title Three</content>
-    </artifact>
-  </title-group>
-</titles>
+<bibitem>
+  <titles>
+    <title-group>
+      <artifact>
+        <content>Title One</content>
+      </artifact>
+      <artifact>
+        <content>Title Two</content>
+      </artifact>
+      <artifact>
+        <content>Title Three</content>
+      </artifact>
+    </title-group>
+  </titles>
+</bibitem>
 ----
 
 [source,yaml]
 ----
 ---
 titles:
-  title-group:
-    - artifact:
-        content: Title One
-    - artifact:
-        content: Title Two
-    - artifact:
-        content: Title Three
+  items:
+    - content: Title One
+    - content: Title Two
+    - content: Title Three
 ----
 
 [source,ruby]
 ----
 class Title < Lutaml::Model::Serializable
   attribute :content, :string
+
+  xml do
+    element "artifact"
+    map_element "content", to: :content
+  end
 end
 
 class TitleCollection < Lutaml::Model::Collection
@@ -4581,7 +4583,7 @@ class BibItem < Lutaml::Model::Serializable
 
   xml do
     element "bibitem"
-    # This overrides the collection's root "title-group"
+    # This wraps the collection's "title-group" root under "titles"
     map_element "titles", to: :titles
   end
 end

data/docs/_pages/breaking-changes.adoc

@@ -143,6 +143,64 @@ end
 Simply remove the `no_root` call - models without `element()` are type-only by default.
 
 
+=== v0.9.0: Strict cardinality validation
+
+Attributes now enforce their declared cardinality. An attribute without
+`collection:` holds a single value, and giving it several is a violation that
+`#validate` reports. See link:validation[Validation] for the full rules.
+
+Four behavior changes come with it.
+
+==== Nested models now run their own validations
+
+`#validate` recurses into nested models and validates each one. Polymorphic,
+required and custom checks on a nested model ran nowhere before; they run now.
+A model that validated clean may start reporting errors its children always had.
+
+==== Singular readers can return arrays
+
+An attribute given more values than it was declared for keeps them all, so
+`#validate` has something to report. Until the violation is fixed, the reader
+returns an array rather than a single value.
+
+[source,ruby]
+----
+obj = Person.from_xml("<person><name>A</name><name>B</name></person>")
+obj.name      # => ["A", "B"]
+obj.validate  # => [#<Lutaml::Model::CollectionTrueMissingError ...>]
+----
+
+Code that assumed a singular reader always returns a scalar should call
+`#validate` before trusting the shape.
+
+While the violation stands the document does not round-trip: serializing writes
+the array out as a single stringified value. Fix the cardinality and output
+returns to normal.
+
+==== Enum shorthand predicates answer false while over-counted
+
+The generated `value?` methods read through the same reader, so an attribute
+holding two values answers `false` for all of them.
+
+[source,ruby]
+----
+obj = Doc.from_json('{"kind": ["draft", "final"]}')
+obj.draft?  # => false, the attribute holds two values
+obj.kind = "draft"
+obj.draft?  # => true
+----
+
+==== Assigning a scalar to a collection attribute wraps it
+
+Assignment now produces the same shape as parsing.
+
+[source,ruby]
+----
+doc.tags = "one"
+doc.tags  # => ["one"]
+----
+
+
 === v0.8.0: XML default namespace behavior
 
 Version 0.8.0 introduces a **breaking change** to XML namespace serialization

data/docs/_pages/collections.adoc

@@ -784,8 +784,6 @@ See link:../_guides/consolidation-mapping[Consolidation Mapping] for the full gu
 
 === Nested collections
 
-TODO: This case needs to be fixed.
-
 Collections can be nested within other models and define their own serialization
 rules.
 
@@ -798,38 +796,42 @@ Data:
 
 [source,xml]
 ----
-<titles>
-  <title-group>
-    <artifact>
-      <content>Title One</content>
-    </artifact>
-    <artifact>
-      <content>Title Two</content>
-    </artifact>
-    <artifact>
-      <content>Title Three</content>
-    </artifact>
-  </title-group>
-</titles>
+<bibitem>
+  <titles>
+    <title-group>
+      <artifact>
+        <content>Title One</content>
+      </artifact>
+      <artifact>
+        <content>Title Two</content>
+      </artifact>
+      <artifact>
+        <content>Title Three</content>
+      </artifact>
+    </title-group>
+  </titles>
+</bibitem>
 ----
 
 [source,yaml]
 ----
 ---
 titles:
-  title-group:
-    - artifact:
-        content: Title One
-    - artifact:
-        content: Title Two
-    - artifact:
-        content: Title Three
+  items:
+    - content: Title One
+    - content: Title Two
+    - content: Title Three
 ----
 
 [source,ruby]
 ----
 class Title < Lutaml::Model::Serializable
   attribute :content, :string
+
+  xml do
+    element "artifact"
+    map_element "content", to: :content
+  end
 end
 
 class TitleCollection < Lutaml::Model::Collection
@@ -846,7 +848,7 @@ class BibItem < Lutaml::Model::Serializable
 
   xml do
     element "bibitem"
-    # This overrides the collection's root "title-group"
+    # This wraps the collection's "title-group" root under "titles"
     map_element "titles", to: :titles
   end
 end
@@ -1667,4 +1669,3 @@ class ReferenceSet < Lutaml::Model::Collection
   end
 end
 ----
-

data/docs/_pages/validation.adoc

@@ -25,14 +25,61 @@ Lutaml::Model supports the following validation types:
 
 === Collection validation
 
-The `collection` option validates collection size ranges.
+The `collection` option sets an attribute's cardinality: `collection: true`
+means `0..*`, a range such as `(1..)` or `(0..5)` bounds the count, and omitting
+it (the default) means `0..1`, a single value.
 
 [source,ruby]
 ----
 attribute :items, :string, collection: (1..)  # At least one item
 attribute :tags, :string, collection: (0..5)  # Up to 5 tags
+attribute :name, :string                      # Default 0..1 (single value)
 ----
 
+A non-collection attribute given multiple values keeps them. Parsing does not
+raise; the values land in the attribute as an array and `#validate` reports
+`Lutaml::Model::CollectionTrueMissingError`, which `#validate!` raises wrapped
+in a `Lutaml::Model::ValidationError`.
+
+[source,ruby]
+----
+obj = Person.from_xml("<person><name>A</name><name>B</name></person>")
+obj.name      # => ["A", "B"]
+obj.validate  # => [#<Lutaml::Model::CollectionTrueMissingError ...>]
+obj.validate! # raises Lutaml::Model::ValidationError
+----
+
+Declare `collection: true` for attributes that hold many values.
+
+The rule is about shape, not count. A singular attribute is declared to hold a
+value, not a list, so a one-element array is still a violation:
+
+[source,ruby]
+----
+Person.from_json('{"name": ["A"]}').validate
+# => [#<Lutaml::Model::CollectionTrueMissingError ...>]
+----
+
+XML has no such distinction — a single `<name>` element is a value, so only a
+repeated element trips the check.
+
+An invalid document does not round-trip. While an attribute holds more values
+than it was declared for, serializing it back out will not reproduce the input.
+Fix the violation and it round-trips normally.
+
+Two cases still report at parse time rather than on `#validate`:
+
+* A declared range that is exceeded raises
+  `Lutaml::Model::CollectionCountOutOfRangeError` for key/value formats.
+* A model mapped onto a plain Ruby class with `model` has no `#validate`, so
+  there is no later point to report to.
+
+A custom deserializer (`with: { from: }`) receives whatever arrived — a single
+node for one occurrence, an array for several, the same shape a custom
+`to:` method already receives for a collection. If that method collapses the
+array to a single value, the over-count is not reported: the method has decided
+what the attribute holds.
+
 === Value enumeration validation
 
 The `values` option validates that an attribute value is one of a fixed set of values.

data/lib/compat/opal/lutaml_model_boot.rb

@@ -163,6 +163,7 @@ require "lutaml/xml/namespace_resolver"
 require "lutaml/xml/namespace_scope_config"
 require "lutaml/xml/namespace_type_resolver"
 require "lutaml/xml/namespace_usage"
+require "lutaml/xml/nested_collection_attribute"
 require "lutaml/xml/oga"
 require "lutaml/xml/parse_session"
 require "lutaml/xml/parsed_namespace_declaration"

data/lib/lutaml/key_value/transform.rb

@@ -272,7 +272,13 @@ format)
                              instance)
         end
 
-        attr.valid_collection!(value, context)
+        # Range errors stay eager here. The over-count error only fires when the
+        # 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.
+        if attr.collection? || !instance.is_a?(Lutaml::Model::Serialize)
+          attr.valid_collection!(value, context)
+        end
         rule.deserialize(instance, value, attributes, self)
       end
 

data/lib/lutaml/model/attribute.rb

@@ -317,9 +317,31 @@ module Lutaml
       end
 
       def cast_value(value, register)
-        return cast_element(value, register) unless collection_instance?(value)
+        if list_like?(value)
+          build_collection(cast_items(value, register), register: register)
+        elsif coerce_to_collection?(value)
+          build_collection(cast_items([value], register), register: register)
+        else
+          cast_element(value, register)
+        end
+      end
+
+      # Plain Arrays count as list input. On singular attributes
+      # collection_instance? matches Arrays too (their collection class is
+      # Array), preserving the Array so strict cardinality can flag it.
+      def list_like?(value)
+        collection_instance?(value) || (collection? && value.is_a?(::Array))
+      end
+
+      # Prepare the seed items for a collection. Custom Collection classes
+      # cast their own items (idempotently) in #initialize, so hand them a
+      # plain array of the existing elements — rebuilding a fresh collection
+      # avoids sharing a mutable default across instances. Plain collections
+      # cast each element here.
+      def cast_items(value, register)
+        return value.to_a if custom_collection?
 
-        build_collection(value.map { |v| cast_element(v, register) })
+        value.map { |v| cast_element(v, register) }
       end
 
       # Apply a value map to transform a value.
@@ -483,10 +505,20 @@ instance_object = nil)
       end
 
       def valid_value!(value)
-        return true if value.nil? && singular?
+        # nil is never tested against the value set, whether it arrives as the
+        # whole value or as one element of a collection (this method recurses
+        # per element). valid_pattern! skips nil the same way, and an unset
+        # attribute is validate_required!'s business, not the enum's.
+        return true if value.nil?
         return true unless enum?
         return true if Utils.uninitialized?(value)
 
+        # Collection attributes hold multiple values; validate each element
+        # against the allowed set rather than the coerced collection itself.
+        if value.is_a?(::Array) || collection_instance?(value)
+          return value.all? { |v| valid_value!(v) }
+        end
+
         unless valid_value?(value)
           raise Lutaml::Model::InvalidValueError.new(name, value, enum_values)
         end
@@ -500,16 +532,17 @@ instance_object = nil)
         options[:values].include?(value)
       end
 
-      # Pattern binds string values only. For a plain :string attribute that is
-      # the resolved type; for a union, the pattern applies to a value that took
-      # the :string branch (a non-string member is exempt). Collections check
-      # each element, so a mix of members validates only its string entries.
-      def valid_pattern!(value, resolved_type)
+      # Pattern binds actual string values only. For a plain :string attribute
+      # every element is a string; for a union the pattern applies to whichever
+      # elements took the :string branch (non-string members are exempt). A nil
+      # element is skipped along with every other non-string, and Array(value)
+      # flattens both plain Arrays and custom Collections so the pattern applies
+      # per element instead of to the collection as a whole.
+      def valid_pattern!(value, _resolved_type)
         return true unless pattern
 
         Array(value).each do |item|
-          next unless resolved_type == Lutaml::Model::Type::String ||
-            item.is_a?(::String)
+          next unless item.is_a?(::String)
           next if pattern.match?(item)
 
           raise Lutaml::Model::PatternNotMatchedError.new(name, pattern, item)
@@ -538,8 +571,11 @@ instance_object = nil)
         end
         resolved_type = type(register)
 
-        valid_value!(value) &&
-          valid_collection!(value, self) &&
+        # Shape before contents. An over-count is a cardinality violation, not
+        # an enum or pattern one, and checking it first keeps those predicates
+        # from reporting on a value whose shape is already wrong.
+        valid_collection!(value, instance_object&.class) &&
+          valid_value!(value) &&
           valid_pattern!(value, resolved_type) &&
           validate_polymorphic!(value, resolved_type) &&
           execute_validations!(value)
@@ -619,7 +655,11 @@ instance_object = nil)
         # Allow any value for unbounded collections
         return true if collection == true
 
-        unless (Utils.uninitialized?(value) && resolved_collection.min.zero?) || collection_instance?(value)
+        unless collection_instance?(value)
+          # An absent value satisfies a zero minimum and has nothing to size.
+          return true if (value.nil? || Utils.uninitialized?(value)) &&
+            resolved_collection.min.zero?
+
           raise Lutaml::Model::CollectionCountOutOfRangeError.new(
             name,
             value,
@@ -627,23 +667,26 @@ instance_object = nil)
           )
         end
 
-        return true unless resolved_collection.is_a?(Range)
+        # cover? rather than between?, so an exclusive range such as (0...5)
+        # rejects a count of 5.
+        in_range = if resolved_collection.end.infinite?
+                     value.size >= resolved_collection.begin
+                   else
+                     resolved_collection.cover?(value.size)
+                   end
 
-        if resolved_collection.is_a?(Range) && resolved_collection.end.infinite?
-          if value.size < resolved_collection.begin
-            raise Lutaml::Model::CollectionCountOutOfRangeError.new(
-              name,
-              value,
-              collection,
-            )
-          end
-        elsif resolved_collection.is_a?(Range) && !resolved_collection.cover?(value.size)
+        unless in_range
           raise Lutaml::Model::CollectionCountOutOfRangeError.new(
             name,
             value,
             collection,
           )
         end
+
+        # Truthy on success: validate_value! chains this with && before the
+        # value/pattern/polymorphic/custom checks, so falling through as nil would
+        # silently skip them for a valid bounded-range collection.
+        true
       end
 
       def serialize(value, format, register, options = {})
@@ -696,7 +739,7 @@ instance_object = nil)
                                       converted: true)
           return build_collection(value.map do |v|
             cast(v, format, register, merged_opts)
-          end)
+          end, register: register)
         end
 
         return value if already_serialized?(resolved_type, value)

data/lib/lutaml/model/collection.rb

@@ -600,7 +600,7 @@ lutaml_register: Lutaml::Model::Config.default_register)
         end
       end
 
-      # Override validate to support both instance and collection-level validations
+      # Adds collection-level validations on top of the instance-level ones
       #
       # Collection-level validations run in order and can share state through a
       # context object. Validations can stop the chain early by calling ctx.stop!
@@ -627,7 +627,10 @@ lutaml_register: Lutaml::Model::Config.default_register)
       #     end
       #   end
       #
-      def validate(register: Lutaml::Model::Config.default_register)
+      # Hooks into the guarded pipeline rather than overriding #validate, so
+      # the collection rules run inside the cycle guard and a self-referencing
+      # collection runs them once rather than twice.
+      def collect_validation_errors(register)
         errors = []
 
         # Run standard instance-level validations first (inherited from Serializable)

data/lib/lutaml/model/collection_handler.rb

@@ -7,6 +7,9 @@ module Lutaml
     # Provides methods for checking if an attribute is a collection,
     # getting the collection class, building collections, and related operations.
     module CollectionHandler
+      # Parameter kinds that carry a named keyword in Method#parameters.
+      KEYWORD_PARAM_KINDS = %i[key keyreq].freeze
+
       # Get the collection options
       #
       # @return [Object, nil] The collection option value
@@ -48,10 +51,50 @@ module Lutaml
 
       # Build a new collection with the given values
       #
+      # Custom Collection classes resolve their item type through the register,
+      # so thread it through when one is supplied. Plain Array collections and
+      # register-less callers keep the prior construction path untouched.
+      #
       # @param args [Array] Values to include in the collection
+      # @param register [Symbol, nil] Register for custom-collection type resolution
       # @return [Object] A new collection instance
-      def build_collection(*args)
-        collection_class.new(args.flatten)
+      def build_collection(*args, register: nil)
+        items = args.flatten
+        unless register && initialize_accepts_register?
+          return collection_class.new(items)
+        end
+
+        collection_class.new(items, lutaml_register: register)
+      end
+
+      # Whether the collection class can be handed a register at construction.
+      #
+      # A custom Collection subclass may override #initialize with the
+      # positional signature that predates the register, and passing the
+      # keyword to one of those raises ArgumentError. Such a subclass resolves
+      # its item types against the default register instead — there is no way
+      # to reach a constructor that does not accept one.
+      #
+      # @return [Boolean] true if #initialize declares the register keyword
+      def initialize_accepts_register?
+        return @initialize_accepts_register if defined?(@initialize_accepts_register)
+
+        @initialize_accepts_register = custom_collection? &&
+          collection_class.instance_method(:initialize).parameters.any? do |kind, param|
+            kind == :keyrest ||
+              (KEYWORD_PARAM_KINDS.include?(kind) && param == :lutaml_register)
+          end
+      end
+
+      # Whether a bare single value assigned to this attribute must be
+      # coerced into a one-element collection, so assignment produces the
+      # same shape as parsing. nil and the uninitialized sentinel pass
+      # through untouched to preserve absent-value semantics.
+      #
+      # @param value [Object] The value being assigned
+      # @return [Boolean] true if the value should be wrapped
+      def coerce_to_collection?(value)
+        collection? && !value.nil? && !Utils.uninitialized?(value)
       end
 
       # Check if this attribute uses a custom collection class

data/lib/lutaml/model/serialize/enum_handling.rb

@@ -81,7 +81,11 @@ module Lutaml
             i = instance_variable_get(:"@#{enum_name}") || []
 
             if !collection && i.is_a?(Array)
-              i.first
+              # A singular enum stores its one value as a one-element array.
+              # Several values is a cardinality violation, so hand the array
+              # on instead of collapsing it — #validate reads through here and
+              # would otherwise never see the over-count.
+              i.size > 1 ? i : i.first
             else
               i.uniq
             end

data/lib/lutaml/model/validation.rb

@@ -3,19 +3,64 @@
 module Lutaml
   module Model
     module Validation
+      # Models being validated on this thread's current stack.
+      VALIDATING_KEY = :lutaml_model_validating
+
+      # Whether a model is already being validated further up this stack.
+      def self.visiting?(model)
+        stack = Thread.current[VALIDATING_KEY]
+        !stack.nil? && stack.key?(model)
+      end
+
+      # The single guarded entry point. A model can appear inside its own
+      # subtree, and re-entering it would recurse forever, so a re-entry
+      # returns early — the outer call is already collecting its errors.
+      #
+      # Override #collect_validation_errors, not this method, to add
+      # validation that must run inside the cycle guard. Overriding #validate
+      # directly puts the override outside the guard.
       def validate(register: Lutaml::Model::Config.default_register)
+        visiting = (Thread.current[VALIDATING_KEY] ||= {}.compare_by_identity)
+        return [] if visiting.key?(self)
+
+        begin
+          # Marked inside the begin, so an exception delivered between the
+          # check and the mark cannot strand an entry on the stack.
+          visiting[self] = true
+          collect_validation_errors(register)
+        ensure
+          visiting.delete(self)
+          Thread.current[VALIDATING_KEY] = nil if visiting.empty?
+        end
+      end
+
+      def collect_validation_errors(register)
         errors = []
 
         self.class.attributes(register).each do |name, attr|
           value = public_send(:"#{name}")
 
           begin
-            if value.is_a?(Lutaml::Model::Serialize)
-              sub_errors = value.validate
+            # Recurse into nested models — a single child or every element of
+            # an array — so their own validation errors surface here. A
+            # Collection is itself a model, so it is validated as one: that
+            # runs its collection-level rules as well as its elements.
+            # #validate takes no arguments here: it is a public override point
+            # that downstream models legitimately define with zero arity.
+            (value.is_a?(::Array) ? value : [value]).each do |item|
+              next unless item.is_a?(Lutaml::Model::Serialize)
+              # Skip a model already on the stack rather than calling into it.
+              # A downstream #validate override sits above the guard, so
+              # re-entering it would run the override's own body a second time.
+              next if Validation.visiting?(item)
+
+              sub_errors = item.validate
               errors.concat(sub_errors) if sub_errors.is_a?(Array)
-            else
-              attr.validate_value!(value, register, instance_object: self)
             end
+
+            # Always run attribute-level validation (cardinality, required,
+            # enum, pattern, polymorphic, custom) regardless of value type.
+            attr.validate_value!(value, register, instance_object: self)
           rescue Lutaml::Model::CollectionCountOutOfRangeError => e
             errors << e unless attr.choice
           rescue Lutaml::Model::InvalidValueError,

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.31"
+    VERSION = "0.8.32"
   end
 end

data/lib/lutaml/xml/format.rb

@@ -128,6 +128,8 @@ module Lutaml
     autoload :TransformationBuilder, "#{__dir__}/transformation_builder"
     autoload :AdapterLoader, "#{__dir__}/adapter_loader"
     autoload :Element, "#{__dir__}/element"
+    autoload :NestedCollectionAttribute,
+             "#{__dir__}/nested_collection_attribute"
     autoload :ModelTransform, "#{__dir__}/model_transform"
     autoload :ParseSession, "#{__dir__}/parse_session"
     autoload :TypeNamespaceResolver, "#{__dir__}/type_namespace_resolver"