lutaml-model 0.8.3 → 0.8.4

data/lib/lutaml/model/validation_framework.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "validation/issue"
+require_relative "validation/layer_result"
+require_relative "validation/report"
+require_relative "validation/context"
+require_relative "validation/rule"
+require_relative "validation/registry"
+require_relative "validation/profile"
+require_relative "validation/remediation"
+require_relative "validation/remediation_result"
+
+module Lutaml
+  module Model
+    # Document-level validation framework. Orthogonal to the existing
+    # attribute-level Validation module — this validates structural
+    # integrity, cross-references, and conformance against domain rules.
+    #
+    # @example Run all registered rules
+    #   issues = Lutaml::Model::Validation.validate(context, registry)
+    # @example Run and raise on errors
+    #   Lutaml::Model::Validation.validate!(context, registry)
+    module Validation
+      class << self
+        def new_registry
+          Registry.new
+        end
+
+        def validate(context, registry, profile: nil)
+          rules = if profile
+                    profile.resolve(registry)
+                  else
+                    registry.all
+                  end
+
+          all_issues = []
+          rules.each do |rule|
+            next unless rule.applicable?(context)
+
+            issues = rule.check(context)
+            if context.respond_to?(:add_error)
+              issues.each { |i| context.add_error(i) }
+            end
+            all_issues.concat(issues)
+          end
+
+          all_issues
+        end
+
+        def validate!(context, registry, profile: nil)
+          issues = validate(context, registry, profile: profile)
+          return if issues.empty?
+
+          errors = issues.select(&:error?)
+          unless errors.empty?
+            raise ValidationError.new(format_errors(errors), issues: errors)
+          end
+        end
+
+        private
+
+        def format_errors(errors)
+          errors.map { |e| "[#{e.code}] #{e.message}" }.join("\n")
+        end
+      end
+
+      class ValidationError < StandardError
+        attr_reader :issues
+
+        def initialize(message, issues: [])
+          super(message)
+          @issues = issues
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.3"
+    VERSION = "0.8.4"
   end
 end

data/lib/lutaml/model.rb

@@ -115,6 +115,8 @@ module Lutaml
              "#{__dir__}/model/error/liquid_not_enabled_error"
     autoload :LiquidClassNotFoundError,
              "#{__dir__}/model/error/liquid_class_not_found_error"
+    autoload :LiquidDropAlreadyRegisteredError,
+             "#{__dir__}/model/error/liquid_drop_already_registered_error"
     autoload :NoAttributesDefinedLiquidError,
              "#{__dir__}/model/error/no_attributes_defined_liquid_error"
     autoload :IncorrectMappingArgumentsError,
@@ -184,6 +186,8 @@ module Lutaml
              "#{__dir__}/model/error/unresolvable_type_error"
     autoload :MixedContentCollectionError,
              "#{__dir__}/model/error/mixed_content_collection_error"
+    autoload :OrderedContentMappingError,
+             "#{__dir__}/model/error/ordered_content_mapping_error"
 
     # Error for passing incorrect model type
     #

data/lib/lutaml/xml/adapter/nokogiri_adapter.rb

@@ -191,9 +191,13 @@ module Lutaml
         def order
           children.filter_map do |child|
             if child.text?
-              next if child.text.nil? || child.text.strip.empty?
+              next if child.text.nil?
 
               Element.new("Text", "text", text_content: child.text)
+            elsif child.comment?
+              Element.new("Comment", "comment",
+                          text_content: child.content,
+                          node_type: :comment)
             else
               Element.new("Element", child.unprefixed_name)
             end
@@ -967,7 +971,7 @@ module Lutaml
           # Pass THIS element as parent so children can inherit namespaces
           child_element_index = 0
           previous_sibling_had_xmlns_blank = false
-          xml_element.children.each do |xml_child|
+          xml_element.children.each do |xml_child| # rubocop:disable Metrics/BlockLength
             # Entity reference nodes are preserved via the marker
             # preprocessing approach in NokogiriAdapter.parse.
             if xml_child.is_a?(Lutaml::Xml::NokogiriElement) &&
@@ -993,6 +997,9 @@ module Lutaml
             elsif xml_child.is_a?(String)
               add_content_node(element, xml_child, doc,
                                cdata: xml_element.cdata && !xml_child.strip.empty?)
+            elsif xml_child.is_a?(::Lutaml::Xml::DataModel::XmlComment)
+              comment_node = doc.create_comment(xml_child.content)
+              element.add_child(comment_node)
             end
           end
 

data/lib/lutaml/xml/adapter/oga_adapter.rb

@@ -549,7 +549,8 @@ module Lutaml
           # 6. Recursively build children by INDEX (PARALLEL TRAVERSAL)
           child_element_index = 0
           xml_element.children.each do |xml_child|
-            if xml_child.is_a?(Lutaml::Xml::DataModel::XmlElement)
+            case xml_child
+            when Lutaml::Xml::DataModel::XmlElement
               child_node = element_node.element_nodes[child_element_index]
               child_element_index += 1
 
@@ -557,9 +558,12 @@ module Lutaml
                                                global_registry, moxml_doc,
                                                element, plan: plan)
               element.add_child(child_element)
-            elsif xml_child.is_a?(String)
+            when String
               add_content_node(element, xml_child, moxml_doc,
                                cdata: xml_element.cdata && !xml_child.strip.empty?)
+            when ::Lutaml::Xml::DataModel::XmlComment
+              comment_node = moxml_doc.create_comment(xml_child.content)
+              element.add_child(comment_node)
             end
           end
 
@@ -833,9 +837,13 @@ module Lutaml
         def order
           children.filter_map do |child|
             if child.text?
-              next if child.text.nil? || child.text.strip.empty?
+              next if child.text.nil?
 
               Element.new("Text", "text", text_content: child.text)
+            elsif child.comment?
+              Element.new("Comment", "comment",
+                          text_content: child.content,
+                          node_type: :comment)
             else
               Element.new("Element", child.unprefixed_name)
             end

data/lib/lutaml/xml/adapter/ox_adapter.rb

@@ -220,14 +220,17 @@ plan: nil)
             # 8. Recursively build children by INDEX (PARALLEL TRAVERSAL)
             child_element_index = 0
             xml_element.children.each do |xml_child|
-              if xml_child.is_a?(Lutaml::Xml::DataModel::XmlElement)
+              case xml_child
+              when Lutaml::Xml::DataModel::XmlElement
                 child_node = element_node.element_nodes[child_element_index]
                 child_element_index += 1
 
                 build_ox_node(xml, xml_child, child_node, global_registry,
                               plan: plan)
-              elsif xml_child.is_a?(String)
+              when String
                 xml.text(xml_child)
+              when ::Lutaml::Xml::DataModel::XmlComment
+                xml.comment(xml_child.content)
               end
             end
           end

data/lib/lutaml/xml/adapter/rexml_adapter.rb

@@ -203,14 +203,17 @@ global_registry, plan)
             # 9. Recursively build children by INDEX (PARALLEL TRAVERSAL)
             child_element_index = 0
             xml_element.children.each do |xml_child|
-              if xml_child.is_a?(Lutaml::Xml::DataModel::XmlElement)
+              case xml_child
+              when Lutaml::Xml::DataModel::XmlElement
                 child_node = element_node.element_nodes[child_element_index]
                 child_element_index += 1
 
                 build_rexml_element(inner_xml, xml_child, child_node,
                                     global_registry, plan)
-              elsif xml_child.is_a?(String)
+              when String
                 inner_xml.text(xml_child)
+              when ::Lutaml::Xml::DataModel::XmlComment
+                inner_xml.comment(xml_child.content)
               end
             end
           end
@@ -246,9 +249,13 @@ global_registry, plan)
         def order
           children.filter_map do |child|
             if child.text?
-              next if child.text.nil? || child.text.strip.empty?
+              next if child.text.nil?
 
               Element.new("Text", child.unprefixed_name)
+            elsif child.comment?
+              Element.new("Comment", "comment",
+                          text_content: child.content,
+                          node_type: :comment)
             else
               Element.new("Element", child.unprefixed_name)
             end

data/lib/lutaml/xml/adapter_element.rb

@@ -41,7 +41,7 @@ module Lutaml
 
                  children = parse_children(node,
                                            default_namespace: default_namespace)
-                 attributes = node_attributes(node)
+                 attributes, attr_order = node_attributes_with_order(node)
                  @root = node
                  EncodingNormalizer.normalize_to_utf8(node.inner_text)
                when Moxml::Text
@@ -63,7 +63,8 @@ module Lutaml
           namespace_prefix: namespace_name,
           default_namespace: default_namespace,
           explicit_no_namespace: explicit_no_namespace || false,
-          node_type: node_type
+          node_type: node_type,
+          attribute_order: attr_order
         )
       end
 
@@ -134,6 +135,29 @@ module Lutaml
         end
       end
 
+      def node_attributes_with_order(node)
+        return [{}, nil] unless node.is_a?(Moxml::Element)
+
+        order = []
+        hash = node.attributes.each_with_object({}) do |attr, h|
+          next if attr_is_namespace?(attr)
+
+          ns_prefix = attr.namespace&.prefix
+          ns_prefix = nil if ns_prefix&.empty?
+
+          attr_name = ns_prefix ? "#{ns_prefix}:#{attr.name}" : attr.name
+          order << attr_name
+
+          h[attr_name] = XmlAttribute.new(
+            attr_name,
+            attribute_value_for_build(attr),
+            namespace: ns_prefix ? attr.namespace&.uri : nil,
+            namespace_prefix: ns_prefix,
+          )
+        end
+        [hash, order.empty? ? nil : order]
+      end
+
       def attribute_value_for_build(attr)
         attr.value
       end

data/lib/lutaml/xml/data_model.rb

@@ -252,6 +252,20 @@ module Lutaml
           result
         end
       end
+
+      # Represents an XML comment in the data model tree.
+      # Stored as a child of XmlElement alongside String (text) and XmlElement children.
+      class XmlComment
+        attr_accessor :content
+
+        def initialize(content)
+          @content = content
+        end
+
+        def to_s
+          "<!--#{content}-->"
+        end
+      end
     end
   end
 end

data/lib/lutaml/xml/document.rb

@@ -94,8 +94,11 @@ module Lutaml
         result = Lutaml::Model::MappingHash.new
         result.node = element
         result.item_order = self.class.order_of(element)
+        result.attribute_order = element.attribute_order
 
         element.children.each do |child|
+          next if child.respond_to?(:comment?) && child.comment?
+
           if klass&.<= Serialize
             attr = klass.attribute_for_child(self.class.name_of(child),
                                              format)

data/lib/lutaml/xml/element.rb

@@ -38,13 +38,18 @@ module Lutaml
         @node_type == :cdata
       end
 
+      # Check if this is a comment node
+      def comment?
+        @node_type == :comment
+      end
+
       # Check if this is a regular element
       def element?
         @node_type == :element
       end
 
       def element_tag
-        @name unless text? || cdata?
+        @name unless text? || cdata? || comment?
       end
 
       def eql?(other)
@@ -71,12 +76,13 @@ module Lutaml
       def infer_node_type(type, name)
         return :text if type == "Text" && name != "#cdata-section"
         return :cdata if name == "#cdata-section" || (type == "Text" && name == "#cdata-section")
+        return :comment if type == "Comment"
 
         :element
       end
 
       def register_liquid_methods
-        %i[text? element_tag type name text_content node_type
+        %i[text? comment? element_tag type name text_content node_type
            cdata? namespace_uri namespace_prefix].each do |attr_name|
           self.class.register_drop_method(attr_name)
         end

data/lib/lutaml/xml/mapping.rb

@@ -101,6 +101,9 @@ module Lutaml
         # Validate mixed content requires collection attribute for content mapping
         validate_mixed_content_collection!(mapper_class)
 
+        # Validate element-only content models do not use map_content
+        validate_ordered_content_mapping!(mapper_class)
+
         # Performance: Clear caches and mark finalized
         @cached_elements.clear
         @cached_attributes.clear
@@ -138,6 +141,12 @@ module Lutaml
                                                              mapper_class)
       end
 
+      def validate_ordered_content_mapping!(mapper_class)
+        return unless @ordered && !@mixed_content && @content_mapping
+
+        raise Lutaml::Model::OrderedContentMappingError.new(mapper_class)
+      end
+
       # Enable mixed content for this element
       #
       # Mixed content means the element can contain both text nodes

data/lib/lutaml/xml/model_transform.rb

@@ -249,6 +249,20 @@ effective_register = nil, instance_is_serialize = nil)
         # Performance: Get namespace_uri once if needed for default_namespace
         namespace_uri = xml_mapping&.namespace_uri
 
+        # Performance: Pre-build Set of child namespaced names for fast rule matching.
+        # This allows skipping value_for_rule for ~91% of rules that have no matching child.
+        child_names_set = nil
+        if doc.respond_to?(:element_children)
+          ec = doc.element_children
+          unless ec.empty?
+            child_names_set = Set.new
+            ec.each do |child|
+              child_names_set.add(child.namespaced_name)
+              child_names_set.add(child.unprefixed_name)
+            end
+          end
+        end
+
         mappings.each do |rule|
           # Performance: Cache rule properties accessed multiple times
           rule.name
@@ -277,6 +291,17 @@ effective_register = nil, instance_is_serialize = nil)
                     doc.root.inner_xml
                   elsif rule.content_mapping?
                     rule.cdata ? doc.cdata : doc.text
+                  elsif child_names_set && !rule.attribute? &&
+                      !child_matches_rule?(rule, child_names_set,
+                                           default_namespace)
+                    # Pre-match: no child element matches this rule.
+                    # Skip expensive value_for_rule, handle defaults inline.
+                    if instance.using_default?(rule_to) || rule.render_default
+                      defaults_used << rule_to
+                      attr&.default(effective_register) || rule.to_value_for(instance)
+                    else
+                      ::Lutaml::Model::UninitializedClass.instance
+                    end
                   else
                     # Performance: Pass cached attr to avoid recomputing attribute_for_rule
                     val = value_for_rule(doc, rule, new_opts, instance, attr,
@@ -339,6 +364,9 @@ effective_register = nil, instance_is_serialize = nil)
 mixed_content_option, xml_mapping = nil,
 instance_is_serialize = nil)
         instance.element_order = doc.root.order
+        if doc.root.respond_to?(:attribute_order) && instance.respond_to?(:attribute_order=)
+          instance.attribute_order = doc.root.attribute_order
+        end
 
         # For Serialize instances, ordered?/mixed? delegate to class mapping.
         # For non-Serialize model classes (model Id), @ordered/@mixed are needed
@@ -939,6 +967,20 @@ effective_register = lutaml_register)
           end
         end
       end
+
+      # Check if any child element in the pre-built Set matches the rule.
+      # Conservative: may return true (false positive) when namespace aliasing
+      # is involved, but never returns false when value_for_rule would find a match.
+      #
+      # @param rule [MappingRule] the mapping rule to check
+      # @param child_names_set [Set] Set of child namespaced_name and unprefixed_name
+      # @param default_namespace [String, nil] the default namespace
+      # @return [Boolean] true if a matching child likely exists
+      def child_matches_rule?(rule, child_names_set, default_namespace)
+        rule_names = rule.namespaced_names(default_namespace)
+        rule_names.any? { |rn| child_names_set.include?(rn) } ||
+          child_names_set.include?(rule.name.to_s)
+      end
     end
   end
 end

data/lib/lutaml/xml/schema/xsd/base.rb

@@ -17,7 +17,10 @@ module Lutaml
           end
 
           def resolved_element_order
-            element_order&.each_with_object(element_order.dup) do |element, array|
+            return nil unless element_order
+
+            filtered = element_order.reject { |e| e.is_a?(Lutaml::Xml::Element) && e.comment? }
+            filtered.each_with_object(filtered.dup) do |element, array|
               next delete_deletables(array, element) if deletable?(element)
 
               update_element_array(array, element)

data/lib/lutaml/xml/serialization/instance_methods.rb

@@ -16,7 +16,8 @@ module Lutaml
         # Writer is used by :eager mode during parsing. Reader delegates to
         # import_declaration_plan which handles lazy building.
         attr_writer :import_declaration_plan
-        attr_accessor :element_order, :schema_location, :encoding, :doctype
+        attr_accessor :element_order, :attribute_order, :schema_location,
+                      :encoding, :doctype
 
         # Store pre-collected namespace data for lazy plan building.
         # This is a plain Hash (no adapter objects) collected during from_xml.
@@ -284,6 +285,7 @@ module Lutaml
           return unless attrs.respond_to?(:item_order)
 
           @element_order = attrs.item_order
+          @attribute_order = attrs.attribute_order if attrs.respond_to?(:attribute_order)
         end
 
         def set_schema_location(attrs)

data/lib/lutaml/xml/transformation/ordered_applier.rb

@@ -153,6 +153,12 @@ text_node_count = 0, use_content_index = false)
                                      text_node_count, use_content_index)
           end
 
+          # For comment nodes, add them directly to preserve position
+          if object.type == "Comment"
+            root.add_child(::Lutaml::Xml::DataModel::XmlComment.new(object.text_content))
+            return :comment_node
+          end
+
           # Find the mapping rule for this element
           rule = find_rule_for_element(object, compiled_rules)
           return nil unless rule
@@ -293,9 +299,19 @@ _options)
         # @param compiled_rules [Array<CompiledRule>] The compiled rules
         # @param mapping [Xml::Mapping] The mapping
         # @param processed_text_nodes [Boolean] Whether text nodes were processed
-        def apply_remaining_rules(_root, _model_instance, options,
+        def apply_remaining_rules(_root, model_instance, options,
 compiled_rules, mapping, processed_text_nodes)
-          compiled_rules.each do |rule|
+          attr_order = model_instance.respond_to?(:attribute_order) &&
+            model_instance.attribute_order
+
+          rules_to_apply = if attr_order
+                             sort_rules_by_attribute_order(compiled_rules,
+                                                           attr_order)
+                           else
+                             compiled_rules
+                           end
+
+          rules_to_apply.each do |rule|
             next if rule.option(:mapping_type) == :element
 
             # Skip content rules if we processed text nodes from element_order
@@ -310,6 +326,34 @@ compiled_rules, mapping, processed_text_nodes)
           end
         end
 
+        # Sort compiled rules so attribute rules follow the captured attribute_order.
+        # Non-attribute rules (content, raw) maintain their original position.
+        #
+        # @param rules [Array<CompiledRule>] The compiled rules
+        # @param attr_order [Array<String>] Attribute names in document order
+        # @return [Array<CompiledRule>] Rules sorted by attribute order
+        def sort_rules_by_attribute_order(rules, attr_order)
+          order_index = attr_order.each_with_index
+            .with_object({}) { |(name, i), h| h[name] = i }
+
+          local_index = attr_order.each_with_index
+            .with_object({}) do |(name, i), h|
+              local = name.include?(":") ? name.split(":", 2).last : name
+              h[local] = i unless h.key?(local)
+            end
+
+          non_attr_rules, attr_rules = rules.partition do |r|
+            r.option(:mapping_type) != :attribute
+          end
+
+          sorted_attr_rules = attr_rules.sort_by do |r|
+            order_index[r.serialized_name] || local_index[r.serialized_name] ||
+              Float::INFINITY
+          end
+
+          non_attr_rules + sorted_attr_rules
+        end
+
         # Check if a mapping rule should be applied based on only/except options
         #
         # @param rule [CompiledRule] The rule to check

data/lib/lutaml/xml/transformation.rb

@@ -292,7 +292,16 @@ module Lutaml
       # @param model_instance [Object] The model instance
       # @param options [Hash] Options
       def apply_standard_rules(root, model_instance, options)
-        compiled_rules.each do |rule|
+        attr_order = model_instance.respond_to?(:attribute_order) &&
+          model_instance.attribute_order
+
+        rules = if attr_order
+                  sort_rules_by_attribute_order(compiled_rules, attr_order)
+                else
+                  compiled_rules
+                end
+
+        rules.each do |rule|
           next unless valid_mapping?(rule, options)
 
           rule_options = options.merge(current_model: model_instance)
@@ -301,6 +310,36 @@ module Lutaml
         end
       end
 
+      # Sort compiled rules so attribute rules follow the captured attribute_order.
+      # Non-attribute rules maintain their original position.
+      #
+      # @param rules [Array<CompiledRule>] The compiled rules
+      # @param attr_order [Array<String>] Attribute names in document order
+      # @return [Array<CompiledRule>] Rules sorted by attribute order
+      def sort_rules_by_attribute_order(rules, attr_order)
+        order_index = attr_order.each_with_index
+          .with_object({}) { |(name, i), h| h[name] = i }
+
+        # Also index by local name (after ':') for namespace-prefixed attributes
+        # e.g., "xlink:href" → "href" so rules with serialized_name "href" can match
+        local_index = attr_order.each_with_index
+          .with_object({}) do |(name, i), h|
+            local = name.include?(":") ? name.split(":", 2).last : name
+            h[local] = i unless h.key?(local)
+          end
+
+        non_attr_rules, attr_rules = rules.partition do |r|
+          r.option(:mapping_type) != :attribute
+        end
+
+        sorted_attr_rules = attr_rules.sort_by do |r|
+          order_index[r.serialized_name] || local_index[r.serialized_name] ||
+            Float::INFINITY
+        end
+
+        non_attr_rules + sorted_attr_rules
+      end
+
       # Serialize a value to string for XML output
       #
       # Delegates to ValueSerializer module

data/lib/lutaml/xml/xml_element.rb

@@ -24,7 +24,7 @@ module Lutaml
       # - :processing_instruction - processing instruction
       NODE_TYPES = %i[element text cdata comment processing_instruction].freeze
 
-      attr_reader :children, :attributes, :namespace_prefix,
+      attr_reader :children, :attributes, :attribute_order, :namespace_prefix,
                   :namespace_prefix_explicit, :parent_document, :node_type
       attr_accessor :adapter_node, :processing_instructions
 
@@ -91,12 +91,14 @@ module Lutaml
       namespace_prefix: nil,
       default_namespace: nil,
       explicit_no_namespace: false,
-      node_type: nil
+      node_type: nil,
+      attribute_order: nil
       )
         @name = name
         @namespace_prefix = namespace_prefix
         @namespace_prefix_explicit = !namespace_prefix.nil? && !namespace_prefix.empty?
         @attributes = attributes
+        @attribute_order = attribute_order
         @children = children
         @text = text
         @parent_document = parent_document
@@ -256,9 +258,7 @@ module Lutaml
 
         @order_cache = children.filter_map do |child|
           if child.text?
-            # Skip whitespace-only text nodes (formatting between elements).
-            # Significant text in mixed content will contain non-whitespace.
-            next if child.text.nil? || child.text.strip.empty?
+            next if child.text.nil?
 
             # For text nodes:
             # - name is "text" for backward compatibility with tests
@@ -276,8 +276,9 @@ module Lutaml
                                      text_content: child.text,
                                      node_type: :cdata)
           elsif child.comment?
-            # Skip comments - they're not part of schema element order
-            nil
+            Lutaml::Xml::Element.new("Comment", "comment",
+                                     text_content: child.text,
+                                     node_type: :comment)
           else
             # For regular elements:
             # - name is the actual element name

data/lutaml-model.gemspec

@@ -35,7 +35,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "bigdecimal"
   spec.add_dependency "canon"
   spec.add_dependency "concurrent-ruby"
-  spec.add_dependency "liquid", "~> 5.0"
+  spec.add_dependency "liquid", ">= 4.0", "< 6.0"
   spec.add_dependency "moxml", ">= 0.1.16"
   spec.add_dependency "ostruct"
   spec.add_dependency "rubyzip", "~> 2.3"