lutaml-xsd 1.1.13 → 1.2.0

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

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xsd
+    module Validation
+      # Resolves instance elements to their schema declarations for the
+      # rule engine's element-scoped dispatch.
+      #
+      # Indexes top-level and inline element declarations across the
+      # repository's schemas. Namespace matching is strict (a target
+      # namespace matches only itself; no-namespace schemas match
+      # no-namespace instances) with a unique-name fallback for corpora
+      # whose instances omit namespaces.
+      #
+      # Deliberately not resolved here (rule-engine backlog): dynamic
+      # typing via xsi:type and derivation closure.
+      class SchemaDefinitionResolver
+        PARTICLE_KINDS = %i[sequence choice all].freeze
+
+        def initialize(repository)
+          @repository = repository
+          @namespaces = {}.compare_by_identity
+          @attributes = Hash.new { |hash, key| hash[key] = [] }
+          @elements = index_elements
+        end
+
+        # Owner schema's target namespace for a resolved declaration
+        # (parsed element models carry no owner-schema link).
+        #
+        # @param schema_element [Object]
+        # @return [String, nil]
+        def target_namespace_for(schema_element)
+          @namespaces[schema_element]
+        end
+
+        # @param name [String] local element name
+        # @param namespace_uri [String, nil] instance element namespace
+        # @return [Lutaml::Xml::Schema::Xsd::Element, nil]
+        def resolve(name, namespace_uri)
+          return nil if name.nil? || name.empty?
+
+          candidates = @elements[name]
+          return nil if candidates.empty?
+
+          exact = candidates.find do |_element, namespace, _kind|
+            namespace_matches?(namespace, namespace_uri)
+          end
+          return exact&.first if exact
+
+          # Unique-name fallback for instances that omit namespaces even
+          # though the schema declares one. A foreign namespace never
+          # falls back.
+          return nil unless namespace_uri.to_s.empty?
+
+          candidates.length == 1 ? candidates.first.first : nil
+        end
+
+        # Named type for an element's `type="prefix:Name"` reference.
+        #
+        # @param schema_element [Lutaml::Xml::Schema::Xsd::Element]
+        # @return [Object, nil]
+        def resolve_type(schema_element)
+          reference = schema_element.type
+          return nil if reference.nil? || reference.to_s.empty?
+
+          resolve_named_type(reference.to_s.split(":").last)
+        end
+
+        # Named complex or simple type by local name.
+        #
+        # @param local_name [String]
+        # @return [Object, nil]
+        def resolve_named_type(local_name)
+          return nil if local_name.nil? || local_name.empty?
+
+          schemas.each do |schema|
+            found = Array(schema.complex_type).find { |ct| ct.name == local_name }
+            return found if found
+
+            found = Array(schema.simple_type).find { |st| st.name == local_name }
+            return found if found
+          end
+          nil
+        end
+
+        # Global attribute declaration by name (for strict xs:anyAttribute
+        # checks).
+        #
+        # @param name [String] local attribute name
+        # @param namespace_uri [String, nil] instance attribute namespace
+        # @return [Lutaml::Xml::Schema::Xsd::Attribute, nil]
+        def resolve_attribute(name, namespace_uri)
+          return nil if name.nil? || name.empty?
+
+          candidates = @attributes[name]
+          return nil if candidates.empty?
+
+          exact = candidates.find do |_attribute, namespace|
+            namespace_matches?(namespace, namespace_uri)
+          end
+          return exact&.first if exact
+
+          return nil unless namespace_uri.to_s.empty?
+
+          candidates.length == 1 ? candidates.first.first : nil
+        end
+
+        # Content-model particle of the element's type, for occurrence
+        # and content-model rules.
+        #
+        # @param schema_element [Lutaml::Xml::Schema::Xsd::Element]
+        # @return [Object, nil]
+        def content_model_for(schema_element)
+          type = schema_element.complex_type || resolve_type(schema_element)
+          particle_for_type(type)
+        end
+
+        # Content-model particle of a NAMED type (for xsi:type overrides).
+        #
+        # @param local_name [String]
+        # @return [Object, nil]
+        def content_model_for_named(local_name)
+          particle_for_type(resolve_named_type(local_name))
+        end
+
+        private
+
+        def particle_for_type(type)
+          return nil unless type.respond_to?(:sequence) || type.respond_to?(:choice) || type.respond_to?(:all)
+
+          direct = Array(type.sequence).first ||
+            Array(type.choice).first || Array(type.all).first
+          return direct if direct
+
+          # Derived types keep their particles under complex_content.
+          if type.respond_to?(:complex_content) && type.complex_content
+            content = type.complex_content
+            part = Array(content.extension).first ||
+              Array(content.restriction).first
+            return particle_for_type(part) if part
+          end
+
+          nil
+        end
+
+        def schemas
+          @schemas ||= @repository.all_schemas.values
+        end
+
+        def namespace_matches?(schema_namespace, instance_namespace)
+          schema_namespace.to_s.empty? == instance_namespace.to_s.empty? &&
+            schema_namespace.to_s == instance_namespace.to_s
+        end
+
+        def index_elements
+          index = Hash.new { |hash, key| hash[key] = [] }
+          schemas.each do |schema|
+            index_schema(index, schema)
+          rescue StandardError
+            # Repositories can carry unparsable entries (broken packages);
+            # they contribute no declarations.
+            next
+          end
+          # Prefer top-level declarations over inline ones.
+          index.each_value do |candidates|
+            candidates.sort_by! { |_element, _ns, kind| kind == :top ? 0 : 1 }
+          end
+          index
+        end
+
+        def index_schema(index, schema)
+          namespace = schema.target_namespace
+          Array(schema.element).each do |element|
+            index_element(index, element, namespace, :top)
+          end
+          Array(schema.complex_type).each do |complex_type|
+            index_type(index, complex_type, namespace)
+          end
+          Array(schema.attribute).each do |attribute|
+            index_attribute(attribute, namespace)
+          end
+        end
+
+        def index_attribute(attribute, namespace)
+          return unless attribute
+          return if attribute.name.nil? || attribute.name.empty?
+
+          @namespaces[attribute] = namespace
+          @attributes[attribute.name] << [attribute, namespace]
+        end
+
+        def index_element(index, element, namespace, kind)
+          return unless element
+
+          @namespaces[element] = namespace
+          unless element.name.nil? || element.name.empty?
+            index[element.name] << [element, namespace, kind]
+          end
+          index_type(index, element.complex_type, namespace) if element.complex_type
+        end
+
+        def index_type(index, complex_type, namespace)
+          return unless complex_type
+
+          each_particle_element(complex_type) do |element|
+            index_element(index, element, namespace, :inline)
+          end
+        end
+
+        def each_particle_element(node, &)
+          return unless node
+
+          if node.is_a?(Array)
+            node.each { |child| each_particle_element(child, &) }
+            return
+          end
+          return if visited_particle?(node)
+
+          PARTICLE_KINDS.each do |kind|
+            next unless node.respond_to?(kind) # optional particle collections
+
+            Array(node.public_send(kind)).each do |particle|
+              next unless particle
+
+              Array(particle.element).each(&)
+              PARTICLE_KINDS.each do |nested|
+                next unless particle.respond_to?(nested)
+
+                each_particle_element(particle.public_send(nested), &)
+              end
+            end
+          end
+
+          return unless node.respond_to?(:complex_content) && node.complex_content
+
+          %i[extension restriction].each do |kind|
+            part = node.complex_content.public_send(kind)
+            each_particle_element(part, &) if part
+          end
+        end
+
+        # Particle collections can be cyclic in parsed models (a nested
+        # sequence pointing back at its container); visit each node once.
+        def visited_particle?(node)
+          @visited ||= {}.compare_by_identity
+          return true if @visited[node]
+
+          @visited[node] = true
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -237,6 +237,7 @@ module Lutaml
                 "validate_facets" => true,
                 "validate_content_models" => true,
                 "validate_namespaces" => true,
+                "engine_validation" => true,
               },
               "error_reporting" => {
                 "include_xpath" => true,

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

@@ -48,9 +48,10 @@ module Lutaml
         #
         # Performs validation in the following order:
         # 1. Parse XML document
-        # 2. Validate structure (elements, namespaces)
-        # 3. Validate types (simple and complex types)
-        # 4. Validate constraints (occurrences, identity constraints)
+        # 2. Engine-native XSD validation (when the adapter provides one)
+        # 3. Validate structure (elements, namespaces)
+        # 4. Validate types (simple and complex types)
+        # 5. Validate constraints (occurrences, identity constraints)
         #
         # @return [ValidationResult] The complete validation result
         def execute
@@ -59,6 +60,8 @@ module Lutaml
           parse_xml
           return result_from_collector if should_stop_after_parse?
 
+          validate_root_declaration
+          run_engine_validation if @config.feature_enabled?(:engine_validation)
           validate_structure if @config.feature_enabled?(:validate_types)
           return result_from_collector if should_stop_after_structure?
 
@@ -68,11 +71,75 @@ module Lutaml
           validate_constraints if @config.feature_enabled?(:validate_occurrences)
           return result_from_collector if should_stop_after_constraints?
 
+          validate_identity if @config.feature_enabled?(:validate_identity_constraints)
+
           result_from_collector
         end
 
         private
 
+        # An instance whose root element is not declared by any schema in
+        # the package can never be valid; surface it explicitly (the
+        # engine's root-matching stays silent for unknown roots, and the
+        # rule engine skips unresolved declarations by design).
+        #
+        # @return [void]
+        def validate_root_declaration
+          root = @document&.root_element
+          return unless root
+
+          resolver = SchemaDefinitionResolver.new(@repository)
+          return if resolver.resolve(root.name, root.namespace_uri)
+
+          @result_collector.add_error(
+            ValidationError.new(
+              code: "element_not_allowed",
+              message: "Root element '#{root.name}' is not declared by any " \
+                       "schema in the package",
+              severity: :error,
+              location: root.xpath,
+              context: {
+                element: root.name,
+                namespace: root.namespace_uri,
+              },
+            ),
+          )
+        rescue ResultCollector::StopValidationError
+          # Stop validation if configured to stop on first error
+        end
+
+        # Validate identity constraints (key/keyref/unique)
+        #
+        # @return [void]
+        def validate_identity
+          return unless @document && @rule_engine
+
+          @rule_engine.execute_category(:identity, @document, @repository)
+        rescue ResultCollector::StopValidationError
+          # Stop validation if configured to stop on first error
+        end
+
+        # Run engine-native XSD validation (Moxml::XSD) when the adapter
+        # supports it. Findings are additive to rule findings.
+        #
+        # @return [void]
+        def run_engine_validation
+          @engine_context ||= EngineContext.compile(@repository)
+          return unless @engine_context&.supported?
+
+          @engine_context.findings_for(@xml_content).each do |finding|
+            @result_collector.add_error(finding)
+          end
+        rescue StandardError => e
+          @result_collector.add_warning(
+            ValidationError.new(
+              code: "engine_validation_unavailable",
+              message: "Engine validation skipped: #{e.message}",
+              severity: :warning,
+            ),
+          )
+        end
+
         # Parse the XML content into a document object
         #
         # @return [void]

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

@@ -41,21 +41,60 @@ module Lutaml
 
         # Execute the validation rule
         #
-        # This is the main entry point for validation. Subclasses must
-        # implement this method to define their validation logic.
+        # This is the main entry point for validation. Rules are
+        # element-scoped: the engine calls this once per instance element
+        # with the schema argument selected by {#schema_argument}.
         #
         # @abstract
-        # @param document [XmlDocument] The XML document to validate
-        # @param repository [SchemaRepository] The schema repository
+        # @param xml_element [XmlElement] The instance element to validate
+        # @param schema_argument [Object, nil] What this rule validates
+        #   against (schema element by default; see {#schema_argument})
         # @param collector [ResultCollector] Collector for validation results
+        # @param repository [SchemaDefinitionResolver, nil] Named-type
+        #   resolution for `type="prefix:Name"` references
         # @return [void]
         #
         # @raise [NotImplementedError] if not implemented by subclass
-        def validate(document, repository, collector)
+        def validate(xml_element, schema_argument, collector, repository: nil)
           raise NotImplementedError,
                 "#{self.class} must implement #validate"
         end
 
+        # The schema object this rule validates the element against.
+        #
+        # Defaults to the resolved schema element; rules that need a
+        # different shape override this (e.g. the occurrence rule wants
+        # the content-model particle).
+        #
+        # @param schema_def [Object, nil] Resolved schema declaration
+        # @param repository [SchemaDefinitionResolver, nil]
+        # @return [Object, nil]
+        def schema_argument(schema_def, repository: nil) # rubocop:disable Lint/UnusedMethodArgument
+          # `repository` is part of the contract; the default selection
+          # does not consult it.
+          schema_def
+        end
+
+        # Whether the rule still runs when no schema declaration resolves.
+        #
+        # @return [Boolean]
+        def runs_without_schema?
+          false
+        end
+
+        XSI_NAMESPACE = "http://www.w3.org/2001/XMLSchema-instance"
+
+        # Find an xsi:-namespaced attribute on the instance element.
+        #
+        # @param xml_element [XmlElement]
+        # @param name [String] local name (e.g. "nil", "type")
+        # @return [XmlAttribute, nil]
+        def xsi_attribute(xml_element, name)
+          xml_element.attributes.find do |attr|
+            attr.name == name && attr.namespace_uri == XSI_NAMESPACE
+          end
+        end
+
         # Get the category of this validation rule
         #
         # Categories are used to group rules and execute them in phases:

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "engine_context"
 require_relative "validation_configuration"
 require_relative "validation_job"
 require_relative "validation_result"
@@ -118,7 +119,7 @@ module Lutaml
         # @return [RuleRegistry] The initialized rule registry
         def build_rule_registry
           require_relative "rule_registry"
-          Validation::RuleRegistry.new(@config)
+          Validation::RuleRegistry.default(@config)
         end
       end
     end

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

@@ -42,7 +42,7 @@ module Lutaml
         #
         # @return [String, nil]
         def namespace_uri
-          @moxml_element.namespace&.href
+          @moxml_element.namespace&.uri
         end
 
         # Get the element's namespace prefix
@@ -84,7 +84,7 @@ module Lutaml
             XmlAttribute.new(
               attr.name,
               attr.value,
-              attr.namespace&.href,
+              attr.namespace&.uri,
               attr.namespace&.prefix,
             )
           end

data/lib/lutaml/xsd/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Xsd
-    VERSION = "1.1.13"
+    VERSION = "1.2.0"
   end
 end

data/lib/lutaml/xsd.rb

@@ -60,3 +60,17 @@ require_relative "xsd/schema_dependency_analyzer"
 require_relative "xsd/type_hierarchy_analyzer"
 require_relative "xsd/xsd_spec_validator"
 require_relative "xsd/cli"
+
+module Lutaml
+  module Xsd
+    # Public parsing entry point, as documented across docs/*.adoc.
+    # Delegates to lutaml-model's XML Schema parser.
+    #
+    # @param xsd [String] XSD content
+    # @param location [String, nil] base location for import/include paths
+    # @return [Lutaml::Xml::Schema::Xsd::Schema]
+    def self.parse(xsd, **)
+      Xml::Schema::Xsd.parse(xsd, **)
+    end
+  end
+end

data/lutaml-xsd.gemspec

@@ -34,9 +34,9 @@ Gem::Specification.new do |spec|
   spec.add_dependency "liquid", ">= 4.0", "< 6.0"
   spec.add_dependency "lutaml-model", "~> 0.8.114"
   spec.add_dependency "lutaml-store", "~> 0.3"
-  spec.add_dependency "moxml"
+  spec.add_dependency "moxml", "~> 0.5.147"
   spec.add_dependency "paint", "~> 2.3"
-  spec.add_dependency "rng", "~> 0.3.5"
+  spec.add_dependency "rng", "~> 0.3.9"
   spec.add_dependency "rubyzip", "~> 3.4"
   spec.add_dependency "table_tennis", "~> 0.0.7"
   spec.add_dependency "thor", "~> 1.0"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-xsd
 version: !ruby/object:Gem::Version
-  version: 1.1.13
+  version: 1.2.0
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 2026-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: liquid
@@ -62,16 +62,16 @@ dependencies:
   name: moxml
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.5.147
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.5.147
 - !ruby/object:Gem::Dependency
   name: paint
   requirement: !ruby/object:Gem::Requirement
@@ -92,14 +92,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.5
+        version: 0.3.9
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.5
+        version: 0.3.9
 - !ruby/object:Gem::Dependency
   name: rubyzip
   requirement: !ruby/object:Gem::Requirement
@@ -190,9 +190,18 @@ files:
 - CLAUDE.md
 - CODE_OF_CONDUCT.md
 - Gemfile
+- Gemfile.lock
 - LICENSE.md
 - README.adoc
 - Rakefile
+- TODO.VISION.md
+- TODO.cleanup.md
+- TODO.conformance.md
+- TODO.docs-spa.md
+- TODO.interop.md
+- TODO.performance.md
+- TODO.som.md
+- benchmark/engines.rb
 - bin/console
 - bin/setup
 - config/base_type_validators.yml
@@ -209,6 +218,7 @@ files:
 - docs/ARCHITECTURE.adoc
 - docs/CHANGELOG.md
 - docs/CLI.adoc
+- docs/CONFORMANCE.adoc
 - docs/CONTRIBUTING.adoc
 - docs/DEPLOYMENT_GUIDE.adoc
 - docs/FAQ.adoc
@@ -217,6 +227,7 @@ files:
 - docs/INSTALLATION.adoc
 - docs/INTERACTIVE_SHELL_DEMO.adoc
 - docs/JING_ALGORITHM_PORTING_GUIDE.md
+- docs/JSON_SCHEMA.adoc
 - docs/LIQUID_METHODS.adoc
 - docs/LXR_PACKAGES.adoc
 - docs/MAINTENANCE_GUIDE.adoc
@@ -266,6 +277,9 @@ files:
 - docs/schema_mapping.adoc
 - docs/schema_repository.adoc
 - docs/schemas/lxr-package-config.schema.json
+- docs/superpowers/plans/2026-10-20-moxml-leptris-migration.md
+- docs/superpowers/specs/2026-10-20-moxml-leptris-migration-design.md
+- docs/superpowers/specs/2026-10-21-rule-engine-wiring-design.md
 - examples/01-simple/README.adoc
 - examples/01-simple/cli/run.sh
 - examples/01-simple/config.yml
@@ -431,6 +445,7 @@ files:
 - lib/lutaml/xsd/conflicts/namespace_conflict.rb
 - lib/lutaml/xsd/conflicts/schema_conflict.rb
 - lib/lutaml/xsd/conflicts/type_conflict.rb
+- lib/lutaml/xsd/conformance/runner.rb
 - lib/lutaml/xsd/coverage_analyzer.rb
 - lib/lutaml/xsd/definition_extractor.rb
 - lib/lutaml/xsd/dependency_grapher.rb
@@ -453,6 +468,7 @@ files:
 - lib/lutaml/xsd/formatters/text_formatter.rb
 - lib/lutaml/xsd/formatters/yaml_formatter.rb
 - lib/lutaml/xsd/interactive_builder.rb
+- lib/lutaml/xsd/json_schema_exporter.rb
 - lib/lutaml/xsd/namespace_mapping.rb
 - lib/lutaml/xsd/namespace_prefix_manager.rb
 - lib/lutaml/xsd/namespace_remapper.rb
@@ -533,6 +549,7 @@ files:
 - lib/lutaml/xsd/validation/base_types/qname_validator.rb
 - lib/lutaml/xsd/validation/base_types/string_validator.rb
 - lib/lutaml/xsd/validation/base_types/time_validator.rb
+- lib/lutaml/xsd/validation/engine_context.rb
 - lib/lutaml/xsd/validation/facets/enumeration_facet_validator.rb
 - lib/lutaml/xsd/validation/facets/facet_validator.rb
 - lib/lutaml/xsd/validation/facets/facet_validator_registry.rb
@@ -553,8 +570,10 @@ files:
 - lib/lutaml/xsd/validation/rules/attribute_validation_rule.rb
 - lib/lutaml/xsd/validation/rules/content_model_validation_rule.rb
 - lib/lutaml/xsd/validation/rules/element_structure_rule.rb
+- lib/lutaml/xsd/validation/rules/identity_constraints_rule.rb
 - lib/lutaml/xsd/validation/rules/occurrence_validation_rule.rb
 - lib/lutaml/xsd/validation/rules/type_validation_rule.rb
+- 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/validation_configuration.rb