lutaml-xsd 1.2.1 → 1.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c78737c6dd26a5aa2ab915675b5fc5ce6316590d776d9ef6d5947988ef804adf
-  data.tar.gz: 56dd63144161aa1f7065067fcc74cf434bf9d40e1e1059c7e48e3cd99da00124
+  metadata.gz: 689df8d8930b23eb8ca6b52c4d435c0e52ea9d654bf64cc51b546fbfe2fcb69e
+  data.tar.gz: 0e58e44689241fdd080621539f438a3f64d7dad94ca55ff72f06740b93320be9
 SHA512:
-  metadata.gz: 89fe169405a033ca52e85b7017e65075167766a5bfba5b2c779483b7ff9ca0ea0a568daa799fdee61009e1e385af0c584b91e7e4af1bbcd578da67501e626107
-  data.tar.gz: b18d6e86f3ee582dbe52ace10581e2ea015681f6742bee4601b5a202e9ebc5e16e1878af8763cee247b2c452a18fe817d4e585cd067b403f5667ef52243c2ae9
+  metadata.gz: 77edb222b3737cc289729cdafe818c083bf12f3aed2f0b3a8251657a92dec54fb9dcd6f0a2464d4da20fb58a39dc9884ca68bf3e5abeeb9ff6122cb3dc269d6c
+  data.tar.gz: 96ccd234460bdfee103628897e869e7c999e510d6d76ddc0a989f990757743dfeea0f7848c9bada3212db900096931fdeaf3e832f4b4f31b6e0a62e6072a4b92

data/Gemfile.lock

@@ -1,9 +1,9 @@
 PATH
   remote: .
   specs:
-    lutaml-xsd (1.2.0)
+    lutaml-xsd (1.2.2)
       liquid (>= 4.0, < 6.0)
-      lutaml-model (~> 0.8.114)
+      lutaml-model (~> 0.8.123)
       lutaml-store (~> 0.3)
       moxml (~> 0.5.147)
       paint (~> 2.3)
@@ -264,7 +264,7 @@ CHECKSUMS
   liquid (5.14.0) sha256=e1020c2b2ee58c7a4d3bfdc7a331537bd27a783353748bff0bf27c6ac0c17065
   lutaml-model (0.8.123) sha256=475f391371965f5baee2a9d018a7c9da8361c3774d3802749aa8805ee1253fde
   lutaml-store (0.3.2) sha256=9c455dbab32b4c635c48a27213f6f56fda191731c4574eb6187184ba0588a672
-  lutaml-xsd (1.2.0)
+  lutaml-xsd (1.2.2)
   memo_wise (1.13.0) sha256=30220c38c4cef410849bc73553c58664dc2c91c6379e4a1df22aea02358b716b
   moxml (0.5.153) sha256=561c6df843edd4a3b7f4c6785f9cfd6fef61050df7f1113fdcd45d8495704fc2
   nokogiri (1.19.4-aarch64-linux-gnu) sha256=1269fb644a6de405057a53dd5c762b1209b43ca7424f839454d3dbc677c31a8f

data/README.adoc

@@ -339,6 +339,28 @@ automatic detection of version-specific features. Validation is automatically
 enabled when parsing schemas via [`Lutaml::Xsd.parse()`](lib/lutaml/xsd.rb:47) but can be disabled
 if needed.
 
+=== Instance validation
+
+Beyond schema-document checks, the `Lutaml::Xsd::Validation` module validates
+XML *instances* against parsed schemas: element structure and content models
+(sequences, choices, nested groups, `xs:any` wildcards with namespace
+constraints and `processContents` enforcement), attribute presence, typing and
+`xs:anyAttribute` on every shape, builtin/simple-type facets, `xsi:nil`
+handling, `xsi:type` dynamic resolution, key/keyref/unique identity
+constraints, and schema-side Unique Particle Attribution checking via
+`Lutaml::Xsd::Validation::UniqueParticleAttribution`.
+
+The pipeline passes 42/42 checks of its conformance corpus
+(`rake conformance`); measured results live in `docs/CONFORMANCE.adoc` and
+`TODO.conformance.md`.
+
+[NOTE]
+====
+Guaranteed feature set requires `lutaml-model >= 0.8.123` (the gemspec
+floor). Keyref resolution and complexType/extension `xs:anyAttribute`
+checking depend on model mappings introduced there.
+====
+
 === Validation checks
 
 The schema validator performs these checks:

data/TODO.conformance.md

@@ -3,17 +3,17 @@
 Goal: conformance is a number, not a feeling. Vendor the W3C XML Schema
 test-suite categories, build the harness, publish the pass-rate, grow it.
 
-## Baseline (2026-10-22, 20 cases / 42 checks, full pass)
+## Baseline (2026-10-23, 21 cases / 45 checks, full pass)
 
-Corpus: 20 case classes under `spec/conformance/cases/`, modelled on the
+Corpus: 21 case classes under `spec/conformance/cases/`, modelled on the
 W3C XML Schema Test Suite category taxonomy — self-authored because the
 canonical 2007 suite distribution is no longer served from w3.org (owner
 can vendor a tarball later; provenance README goes with it).
 
 | mode | pass-rate |
 |---|---|
-| engine (Moxml::XSD tier-1, leptris 1.9.380.2) | 38/42 (90.5%) |
-| pipeline (ValidationJob + wired rule engine) | 42/42 (100.0%) |
+| engine (Moxml::XSD tier-1, leptris 1.9.380.2) | 38/42 (90.5%, 1 case unsupported) |
+| pipeline (ValidationJob + wired rule engine) | 45/45 (100.0%) |
 
 The pipeline now passes every check in the corpus. The engine trails on
 four: strict wildcard/anyAttribute under-detection, xsi:nil on
@@ -27,7 +27,8 @@ History: 2026-10-20 baseline 20/25 (80.0%) with pipeline == engine
 baseline 34/39 (87.2%); gap rules 37/39 (94.9%); anyAttribute 40/42
 (95.2%); keyref activation via lutaml-model 0.8.121 → 41/42 (97.6%);
 lutaml-model 0.8.123 (complexType/extension anyAttribute mappings) +
-leptris 1.9.380.2 → 42/42 (100.0%).
+leptris 1.9.380.2 → 42/42 (100.0%); xs:group expansion in the content
+and occurrence walks grew the corpus to 45 checks → 45/45 (100.0%).
 
 Remaining engine-mode gaps (tracked, moxml/leptris-side):
 
@@ -89,7 +90,21 @@ Remaining engine-mode gaps (tracked, moxml/leptris-side):
       resolution (unknown-type rejection; content walk follows the
       override); the engine's valid-derived false positive is fixed in
       leptris 1.9.380.2 (moxml#433)
-- [ ] Particle checking: UPA detection — DEFERRED (engine covers the
-      tier-1 subset; UPA is schema-side checking)
+- [x] Particle checking: UPA detection (2026-10-22) —
+      `UniqueParticleAttribution` schema-side checker: first-set
+      computation over sequence/choice/all with wildcard/element
+      overlap, choice-alternative and sequence-junction conflict rules,
+      container occurrence folding. Standalone API
+      (`findings` → upa_violation findings); zero findings on the
+      conformance corpus schemas (no false positives). Depth (2026-10-22):
+      xs:group references expand to the referenced declaration
+      (cycle-guarded), and element first-sets include substitution-group
+      members — head/member junctions report per XSD 1.0 while required
+      head/member sequences stay deterministic. Wired into
+      `ValidationJob` as an opt-out `validate_upa` phase: schema
+      findings surface as warnings and never flip instance validity.
+      Also fixed the occurrence rule's choice counting: one instance
+      element matching duplicate alternatives counts once, not once
+      per alternative
 - [ ] XSD 1.1 constructs behind a version flag — DEFERRED: 1.1 strategy
       decision needed (see TODO.som.md)

data/docs/CONFORMANCE.adoc

@@ -32,9 +32,17 @@ Two modes are measured independently:
 
 ## Baseline and gap register
 
-Recorded in `TODO.conformance.md` (2026-10-20: 20/25 = 80.0% in both
-modes). Each failing check maps to a tracked gap; the gap register is the
-work queue for the conformance pillar.
+Current measured result (2026-10-23, 20 case classes / 42 checks):
+
+- **pipeline** — 42/42 (100.0%)
+- **engine** — 38/42 (90.5%); the four remaining are documented tier-1
+  laxness (strict wildcard and anyAttribute under-detection, `xsi:nil` on
+  non-nillable elements, wrong-namespace root matching), tracked in
+  lutaml/moxml#452
+
+The full history and gap register live in `TODO.conformance.md`; each
+failing check maps to a tracked gap, and the register is the work queue
+for the conformance pillar.
 
 ## Adding a case
 

data/lib/lutaml/xsd/validation/rules/content_model_validation_rule.rb

@@ -129,6 +129,10 @@ module Lutaml
                 # occurrence constraints survive the walk.
                 if particle.is_a?(Lutaml::Xsd::Sequence)
                   particles.concat(collect_particles(particle))
+                elsif particle.is_a?(Lutaml::Xml::Schema::Xsd::Group)
+                  particles.concat(
+                    expand_group_container(particle, repository),
+                  )
                 else
                   particles << particle
                 end
@@ -181,7 +185,8 @@ module Lutaml
               # enforced loosely for the same reason.
               container = particle.is_a?(Lutaml::Xsd::Sequence) ||
                 particle.is_a?(Lutaml::Xsd::Choice) ||
-                particle.is_a?(Lutaml::Xsd::All)
+                particle.is_a?(Lutaml::Xsd::All) ||
+                particle.is_a?(Lutaml::Xml::Schema::Xsd::Group)
               max_occurs = parse_max_occurs(
                 particle.max_occurs, container ? :unbounded : 1
               )
@@ -429,20 +434,28 @@ module Lutaml
           #   wildcard namespace constraints scoped to the target namespace
           # @return [Boolean]
           def particle_matches?(xml_element, particle, repository = nil,
-                                parent: nil)
+                                parent: nil, group_depth: 0)
             case particle
             when Lutaml::Xsd::Element
               element_matches?(xml_element, particle, repository)
             when Lutaml::Xsd::Any
               wildcard_permits?(particle, parent || xml_element,
                                 xml_element, repository)
+            when Lutaml::Xml::Schema::Xsd::Group
+              expand_group_container(particle, repository,
+                                     group_depth).any? do |container|
+                particle_matches?(xml_element, container, repository,
+                                  parent: parent,
+                                  group_depth: group_depth + 1)
+              end
             when Lutaml::Xsd::Sequence, Lutaml::Xsd::Choice, Lutaml::Xsd::All
               # Nested content model: a child matches the container when it
               # matches any leaf particle inside it. Inner ordering is
               # permissive; the outer walk stays sequential.
               collect_particles(particle).any? do |leaf|
                 particle_matches?(xml_element, leaf, repository,
-                                  parent: parent)
+                                  parent: parent,
+                                  group_depth: group_depth)
               end
             else
               false

data/lib/lutaml/xsd/validation/rules/occurrence_validation_rule.rb

@@ -65,6 +65,11 @@ module Lutaml
             when Lutaml::Xsd::All
               validate_all_occurrences(parent_element, schema_particle,
                                        collector, repository: repository)
+            when Lutaml::Xml::Schema::Xsd::Group
+              expand_group_container(schema_particle, repository).each do |container|
+                validate(parent_element, container, collector,
+                         repository: repository)
+              end
             end
           end
 
@@ -265,15 +270,33 @@ module Lutaml
           # @return [Integer]
           def count_choice_alternatives(parent_element, choice,
                                         repository = nil)
-            return 0 if choice.element.empty?
+            return 0 if choice.element.empty? || parent_element.children.empty?
 
             alternatives = Array(choice.element)
-            alternatives.count do |alt_element|
-              count_element_occurrences(parent_element, alt_element,
-                                        repository).positive?
+            # Count instance elements that matched the choice — a single
+            # child matching several identical alternatives counts once.
+            parent_element.children.count do |child|
+              alternatives.any? do |alt_element|
+                count_element_occurrences_for_child(child, alt_element,
+                                                    parent_element,
+                                                    repository)
+              end
             end
           end
 
+          # Whether one instance child matches one alternative declaration.
+          def count_element_occurrences_for_child(child, schema_element,
+                                                  _parent_element,
+                                                  repository)
+            element_name = schema_element.name ||
+              schema_element.ref.to_s.split(":").last
+            target_ns = resolve_target_namespace(schema_element, repository)
+
+            (child.name == element_name &&
+              namespaces_match?(child.namespace_uri, target_ns)) ||
+              substitution_member?(child, schema_element, repository)
+          end
+
           # Validate minimum occurrence constraint
           #
           # @param parent_element [XmlElement] Parent element

data/lib/lutaml/xsd/validation/schema_definition_resolver.rb

@@ -25,6 +25,7 @@ module Lutaml
             %i[sequence choice all],
           Lutaml::Xml::Schema::Xsd::RestrictionComplexContent =>
             %i[sequence choice all],
+          Lutaml::Xml::Schema::Xsd::Group => %i[sequence choice all],
           Lutaml::Xml::Schema::Xsd::Sequence => %i[sequence choice],
           Lutaml::Xml::Schema::Xsd::Choice => %i[sequence choice],
           Lutaml::Xml::Schema::Xsd::All => [].freeze,
@@ -123,6 +124,21 @@ module Lutaml
           candidates.length == 1 ? candidates.first.first : nil
         end
 
+        # Named group declaration by local name (for xs:group reference
+        # expansion in the content and occurrence walks).
+        #
+        # @param local_name [String]
+        # @return [Lutaml::Xml::Schema::Xsd::Group, nil]
+        def resolve_group(local_name)
+          return nil if local_name.nil? || local_name.empty?
+
+          schemas.each do |schema|
+            found = Array(schema.group).find { |g| g.name == local_name }
+            return found if found
+          end
+          nil
+        end
+
         # Content-model particle of the element's type, for occurrence
         # and content-model rules.
         #
@@ -147,7 +163,8 @@ module Lutaml
           case type
           when Lutaml::Xml::Schema::Xsd::ComplexType
             direct = Array(type.sequence).first ||
-              Array(type.choice).first || Array(type.all).first
+              Array(type.choice).first || Array(type.all).first ||
+              Array(type.group).first
             return direct if direct
 
             # Derived types keep their particles under complex_content.
@@ -202,6 +219,11 @@ module Lutaml
           Array(schema.attribute).each do |attribute|
             index_attribute(attribute, namespace)
           end
+          Array(schema.group).each do |group|
+            each_particle_element(group) do |element|
+              index_element(index, element, namespace, :inline)
+            end
+          end
         end
 
         def index_attribute(attribute, namespace)

data/lib/lutaml/xsd/validation/unique_particle_attribution.rb

@@ -0,0 +1,345 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xsd
+    module Validation
+      # Schema-side Unique Particle Attribution checking (XSD 1.0 §3.8.6).
+      #
+      # Reports content models where an instance element could match more
+      # than one particle, making a valid document's interpretation
+      # ambiguous:
+      # - xs:choice: overlapping first-sets between alternatives
+      # - xs:sequence: a nullable or repeatable particle followed by a
+      #   particle matching the same first element
+      # - element vs wildcard and wildcard vs wildcard overlaps at the
+      #   same junctions
+      #
+      # First-sets are computed recursively over nested
+      # sequence/choice/all containers; xs:group references are treated
+      # as opaque (not descended) and contribute no names.
+      #
+      #     findings = UniqueParticleAttribution.new(schema).findings
+      #     findings.each { |f| puts "#{f.code}: #{f.message}" }
+      class UniqueParticleAttribution
+        Finding = Struct.new(:code, :message, :path, keyword_init: true)
+
+        FirstSet = Struct.new(:names, :wildcards, :nullable, :repeatable) do
+          def merge(other)
+            FirstSet.new(
+              names | other.names,
+              wildcards | other.wildcards,
+              nullable || other.nullable,
+            )
+          end
+
+          def overlaps?(other)
+            names.intersect?(other.names) ||
+              wildcards.any? { |w| other.wildcards.any? { |o| wildcard_overlap?(w, o) } } ||
+              wildcards.any? { |w| other.names.any? { |name| wildcard_admits?(w, name) } } ||
+              other.wildcards.any? { |w| names.any? { |name| wildcard_admits?(w, name) } }
+          end
+
+          private
+
+          # Conservative wildcard-pair overlap: ##any overlaps everything;
+          # distinct constraints are treated as overlapping only when
+          # identical (##local, ##other, lists, single namespaces).
+          def wildcard_overlap?(left, right)
+            left == right || left == "##any" || right == "##any"
+          end
+
+          def wildcard_admits?(wildcard, (namespace, _name))
+            case wildcard
+            when "##any", "" then true
+            when "##local" then namespace.empty?
+            when "##other" then !namespace.empty?
+            when "##targetNamespace" then false
+            else wildcard.split(/\s+/).include?(namespace)
+            end
+          end
+        end
+
+        EMPTY_FIRST = FirstSet.new([].freeze, [].freeze, true).freeze
+
+        # @param schema [Lutaml::Xml::Schema::Xsd::Schema] parsed schema
+        def initialize(schema)
+          @schema = schema
+          @seen = {}.compare_by_identity
+          @groups = {}
+          Array(@schema.group).each do |group|
+            @groups[group.name.to_s] = group if group.name
+          end
+          @substitutes = {}
+          Array(@schema.element).each do |element|
+            next unless element.name && element.substitution_group.to_s.match?(/\S/)
+
+            head = element.substitution_group.to_s.split(":").last
+            (@substitutes[head] ||= []) << element
+          end
+        end
+
+        # @return [Array<Finding>] UPA violations, empty when deterministic
+        def findings
+          compute! unless @computed
+          @findings
+        end
+
+        private
+
+        def compute!
+          @findings = []
+          Array(@schema.element).each do |element|
+            check_type(element.complex_type, "/#{element.name}") if
+              element.complex_type
+          end
+          Array(@schema.complex_type).each do |complex_type|
+            check_type(complex_type, complex_type.name.to_s)
+          end
+          @computed = true
+        end
+
+        def check_type(type, path)
+          return unless type.is_a?(Lutaml::Xml::Schema::Xsd::ComplexType)
+
+          container = type.sequence || type.choice || type.all
+          check_container(container, path) if container
+        end
+
+        # Walks a container: checks its own junctions, then descends.
+        def check_container(container, path)
+          return unless container
+          return if @seen[container]
+
+          @seen[container] = true
+
+          particles = ordered_particles(container)
+          check_junctions(particles, container, path)
+          particles.each do |particle|
+            case particle
+            when Lutaml::Xsd::Sequence, Lutaml::Xsd::Choice, Lutaml::Xsd::All
+              check_container(particle, "#{path}/#{particle_name(particle)}")
+            end
+          end
+        end
+
+        def check_junctions(particles, container, path)
+          firsts = particles.map { |p| first_set(p) }
+
+          if container.is_a?(Lutaml::Xsd::Choice)
+            check_choice_overlap(particles, firsts, path)
+          else
+            check_sequence_junctions(particles, firsts, path)
+          end
+        end
+
+        def check_choice_overlap(particles, firsts, path)
+          firsts.each_with_index do |first, i|
+            firsts[(i + 1)..].each_with_index do |other, j|
+              next unless first.overlaps?(other)
+
+              report(
+                path,
+                "ambiguous choice: '#{particle_name(particles[i])}' and " \
+                "'#{particle_name(particles[i + 1 + j])}' can match the " \
+                "same element",
+              )
+            end
+          end
+        end
+
+        def check_sequence_junctions(particles, firsts, path)
+          firsts.each_with_index do |first, i|
+            next if i.zero?
+
+            previous = firsts[i - 1]
+            next unless previous.nullable || previous.repeatable
+            next unless first.overlaps?(previous)
+
+            report(
+              path,
+              "ambiguous sequence: '#{particle_name(particles[i - 1])}' " \
+              "can be followed by '#{particle_name(particles[i])}' — both " \
+              "match the same first element",
+            )
+          end
+        end
+
+        def report(path, message)
+          @findings << Finding.new(
+            code: "upa_violation",
+            message: message,
+            path: path,
+          )
+        end
+
+        # First-set of a particle: the element names and wildcards it can
+        # match first, and whether it can be absent. Repeatable marks
+        # particles whose occurrence permits more than one match.
+        def first_set(particle)
+          case particle
+          when Lutaml::Xml::Schema::Xsd::Element
+            FirstSet.new(element_keys(particle), [].freeze,
+                         parse_min(particle).zero?).tap do |first|
+              first.repeatable = parse_max(particle) != 1
+            end
+          when Lutaml::Xsd::Any
+            FirstSet.new([].freeze, [wildcard_spec(particle)].compact,
+                         parse_min(particle).zero?).tap do |first|
+              first.repeatable = parse_max(particle) != 1
+            end
+          when Lutaml::Xsd::Sequence
+            apply_occurrence(sequence_first(particle), particle)
+          when Lutaml::Xsd::Choice, Lutaml::Xsd::All
+            apply_occurrence(choice_first(particle), particle)
+          else
+            EMPTY_FIRST
+          end
+        end
+
+        # A container particle's own occurrence widens its computed
+        # first-set: minOccurs="0" makes it nullable, max≠1 repeatable.
+        def apply_occurrence(first, particle)
+          first.nullable ||= parse_min(particle).zero?
+          first.repeatable ||= parse_max(particle) != 1
+          first
+        end
+
+        # Leading names until the first required, exactly-once particle;
+        # nullable only when every particle can be absent.
+        def sequence_first(sequence)
+          names = []
+          wildcards = []
+          nullable = true
+          repeatable = false
+          ordered_particles(sequence).each do |particle|
+            first = first_set(particle)
+            names |= first.names
+            wildcards |= first.wildcards
+            repeatable ||= first.repeatable
+            unless first.nullable
+              nullable = false
+              break
+            end
+          end
+          FirstSet.new(names, wildcards, nullable).tap do |first|
+            first.repeatable = repeatable
+          end
+        end
+
+        def choice_first(choice)
+          names = []
+          wildcards = []
+          nullable = false
+          repeatable = false
+          ordered_particles(choice).each do |particle|
+            first = first_set(particle)
+            names |= first.names
+            wildcards |= first.wildcards
+            nullable ||= first.nullable
+            repeatable ||= first.repeatable
+          end
+          FirstSet.new(names, wildcards, nullable).tap do |first|
+            first.repeatable = repeatable
+          end
+        end
+
+        # Particles in declaration order — resolved_element_order preserves
+        # the source sequence including xs:any, which attribute-style
+        # accessor reads would reorder. xs:group references expand to the
+        # referenced declaration's particles (cycle-guarded per chain).
+        def ordered_particles(container, group_chain = {})
+          ordered = container.resolved_element_order
+          raw = if ordered.to_a.any?
+                  ordered.to_a
+                else
+                  case container
+                  when Lutaml::Xml::Schema::Xsd::Sequence,
+                       Lutaml::Xml::Schema::Xsd::Choice
+                    %i[element any sequence choice].flat_map do |kind|
+                      Array(container.public_send(kind))
+                    end.compact
+                  when Lutaml::Xml::Schema::Xsd::All
+                    Array(container.element).compact
+                  else
+                    []
+                  end
+                end
+          raw.flat_map do |particle|
+            if particle.is_a?(Lutaml::Xml::Schema::Xsd::Group)
+              expand_group(particle, group_chain)
+            else
+              [particle]
+            end
+          end
+        end
+
+        def expand_group(group_ref, chain)
+          local = (group_ref.ref || group_ref.name).to_s.split(":").last
+          declaration = @groups[local]
+          return [] unless declaration
+          return [] if chain[local]
+
+          chain[local] = true
+          ordered_particles(declaration, chain)
+        end
+
+        # An element particle matches its own name plus every member of
+        # the substitution group headed by it.
+        def element_keys(element)
+          own = element_key(element)
+          return [] unless own
+
+          members = @substitutes.fetch(own[1], [])
+          [own] + members.filter_map do |member|
+            member.name ? [@schema.target_namespace.to_s, member.name] : nil
+          end
+        end
+
+        def element_key(element)
+          name = element.name || element.ref
+          return nil if name.to_s.empty?
+
+          namespace = if element.name
+                        element.target_namespace.to_s
+                      else
+                        @schema.target_namespace.to_s
+                      end
+          [namespace, name.to_s]
+        end
+
+        def wildcard_spec(any_particle)
+          any_particle.namespace.to_s
+        end
+
+        def parse_min(particle)
+          value = particle.min_occurs.to_s
+          value.empty? ? 1 : value.to_i
+        rescue StandardError
+          1
+        end
+
+        def parse_max(particle)
+          value = particle.max_occurs.to_s
+          return Float::INFINITY if value == "unbounded"
+          return 1 if value.empty?
+
+          value.to_i
+        rescue StandardError
+          1
+        end
+
+        def particle_name(particle)
+          case particle
+          when Lutaml::Xml::Schema::Xsd::Element
+            particle.name || particle.ref || "element"
+          when Lutaml::Xsd::Any then "any"
+          when Lutaml::Xsd::Choice then "choice"
+          when Lutaml::Xsd::Sequence then "sequence"
+          when Lutaml::Xsd::All then "all"
+          else particle.class.name.split("::").last
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/xsd/validation/validation_job.rb

@@ -5,6 +5,7 @@ require_relative "validation_error"
 require_relative "xml_navigator"
 require_relative "result_collector"
 require_relative "rule_engine"
+require_relative "unique_particle_attribution"
 
 module Lutaml
   module Xsd
@@ -62,6 +63,7 @@ module Lutaml
 
           validate_root_declaration
           run_engine_validation if @config.feature_enabled?(:engine_validation)
+          run_upa_validation if @config.feature_enabled?(:validate_upa)
           validate_structure if @config.feature_enabled?(:validate_types)
           return result_from_collector if should_stop_after_structure?
 
@@ -119,6 +121,33 @@ module Lutaml
           # Stop validation if configured to stop on first error
         end
 
+        # Schema-side UPA checking (XSD 1.0 3.8.6). Findings describe the
+        # schema rather than the instance, so they surface as warnings.
+        #
+        # @return [void]
+        def run_upa_validation
+          @repository.all_schemas.each_value do |schema|
+            UniqueParticleAttribution.new(schema).findings.each do |finding|
+              @result_collector.add_warning(
+                ValidationError.new(
+                  code: finding.code,
+                  message: finding.message,
+                  severity: :warning,
+                  context: { schema_path: finding.path },
+                ),
+              )
+            end
+          end
+        rescue StandardError => e
+          @result_collector.add_warning(
+            ValidationError.new(
+              code: "upa_validation_unavailable",
+              message: "UPA validation skipped: #{e.message}",
+              severity: :warning,
+            ),
+          )
+        end
+
         # Run engine-native XSD validation (Moxml::XSD) when the adapter
         # supports it. Findings are additive to rule findings.
         #

data/lib/lutaml/xsd/validation/validation_rule.rb

@@ -210,6 +210,23 @@ module Lutaml
 
         protected
 
+        # The container an xs:group reference expands to (the declaration's
+        # sequence/choice/all), kept whole — matching descends into it.
+        # XSD 1.0 forbids recursive groups; the depth guard only defends
+        # against malformed schemas.
+        def expand_group_container(group, repository, depth = 0)
+          return [] unless repository
+          return [] if depth > 5
+
+          local = (group.ref || group.name).to_s.split(":").last
+          declaration = repository.resolve_group(local)
+          return [] unless declaration
+
+          container = Array(declaration.sequence).first ||
+            Array(declaration.choice).first || Array(declaration.all).first
+          container ? [container] : []
+        end
+
         # Helper method to create validation errors
         #
         # @param collector [ResultCollector] The result collector

data/lib/lutaml/xsd/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Xsd
-    VERSION = "1.2.1"
+    VERSION = "1.2.3"
   end
 end

data/lutaml-xsd.gemspec

@@ -32,7 +32,7 @@ Gem::Specification.new do |spec|
   end
 
   spec.add_dependency "liquid", ">= 4.0", "< 6.0"
-  spec.add_dependency "lutaml-model", "~> 0.8.114"
+  spec.add_dependency "lutaml-model", "~> 0.8.123"
   spec.add_dependency "lutaml-store", "~> 0.3"
   spec.add_dependency "moxml", "~> 0.5.147"
   spec.add_dependency "paint", "~> 2.3"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-xsd
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.2.3
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-22 00:00:00.000000000 Z
+date: 2026-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: liquid
@@ -36,14 +36,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.114
+        version: 0.8.123
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.114
+        version: 0.8.123
 - !ruby/object:Gem::Dependency
   name: lutaml-store
   requirement: !ruby/object:Gem::Requirement
@@ -576,6 +576,7 @@ files:
 - lib/lutaml/xsd/validation/schema_definition_resolver.rb
 - lib/lutaml/xsd/validation/schema_location_extractor.rb
 - lib/lutaml/xsd/validation/schema_resolver.rb
+- lib/lutaml/xsd/validation/unique_particle_attribution.rb
 - lib/lutaml/xsd/validation/validation_configuration.rb
 - lib/lutaml/xsd/validation/validation_error.rb
 - lib/lutaml/xsd/validation/validation_job.rb