lutaml-model 0.8.2 → 0.8.4

data/docs/_guides/document-validation.adoc

@@ -0,0 +1,303 @@
+---
+title: Document Validation Framework
+nav_order: 12
+parent: Guides
+---
+
+# Document Validation Framework
+:toc:
+:toclevels: 3
+
+== Overview
+
+Lutaml::Model provides a document-level validation framework
+(`Lutaml::Model::Validation`) for validating structural integrity,
+cross-references, and conformance against domain-specific rules.
+
+This framework is **orthogonal** to the existing attribute-level validation
+(`validate`/`validate!` on model instances). Attribute validation checks type
+constraints, enumerations, and collection sizes. The document validation
+framework checks document-level concerns like structural integrity,
+cross-references, and conformance rules.
+
+The framework is designed for reuse across the lutaml ecosystem
+(uniword, svg_conform, lutaml-model) and follows open/closed principles --
+you extend it by subclassing, not by modifying framework code.
+
+== Core components
+
+=== Issue
+
+`Lutaml::Model::Validation::Issue` is a `Lutaml::Model::Serializable` subclass
+representing a validation finding.
+
+[source,ruby]
+----
+issue = Lutaml::Model::Validation::Issue.new(
+  severity: "error",        # "error", "warning", "info", or "notice"
+  code: "DOC-020",          # Rule-specific code
+  message: "Missing author",# Human-readable description
+  location: "word/document.xml",  # Optional: file path or XPath
+  line: 42,                 # Optional: line number
+  suggestion: "Add an author element" # Optional: fix hint
+)
+
+issue.error?    # => true
+issue.warning?  # => false
+
+# Serializable to JSON/YAML
+issue.to_json
+----
+
+Severity values are validated against `Issue::SEVERITIES` (`%w[error warning info notice]`).
+Invalid severities raise `ArgumentError`.
+
+=== Rule
+
+`Lutaml::Model::Validation::Rule` is an abstract base class. Subclass it and
+override methods to implement domain-specific validation logic.
+
+[source,ruby]
+----
+class FontConsistencyRule < Lutaml::Model::Validation::Rule
+  def code = "DOC-010"
+  def category = :fonts
+  def severity = "warning"
+
+  def applicable?(context)
+    context.key?(:fonts)
+  end
+
+  def check(context)
+    fonts = context[:fonts]
+    return [] if fonts.length <= 1
+
+    [issue("Document uses #{fonts.length} different fonts")]
+  end
+end
+----
+
+Key methods to override:
+
+|===
+| Method | Default | Description
+
+| `code` | `nil` | Unique rule identifier (e.g., "DOC-010")
+| `category` | `:general` | Rule category for filtering
+| `severity` | `"error"` | Default severity for issues
+| `applicable?(context)` | `true` | Whether to run this rule for the given context
+| `check(context)` | `[]` | Returns an `Array<Issue>` of findings
+| `needs_deferred?` | `false` | For streaming validation
+| `complete(context)` | `[]` | Final issues after deferred collection
+|===
+
+Use the private `issue(message, **overrides)` helper inside `check` to create
+issues that inherit the rule's severity and code by default.
+
+=== Registry
+
+`Lutaml::Model::Validation::Registry` is an instance-based rule store with
+cached instantiation.
+
+[source,ruby]
+----
+registry = Lutaml::Model::Validation::Registry.new
+
+# Register rule classes (instances are cached after first materialization)
+registry.register(FontConsistencyRule)
+registry.register(RequiredFieldsRule)
+
+# Query — instances are cached, subsequent calls return the same objects
+registry.all              # => [#<FontConsistencyRule>, #<RequiredFieldsRule>]
+registry.find("DOC-010")  # => #<FontConsistencyRule>
+registry.for_category(:fonts)  # => [#<FontConsistencyRule>]
+registry.size             # => 2
+
+# Duplicate registration is prevented
+registry.register(FontConsistencyRule)  # no-op
+registry.size             # => 2
+
+# Reset clears both classes and cached instances
+registry.reset!
+----
+
+NOTE: Rule instances are cached after the first call to `all`, `find`, or
+`for_category`. Registering a new rule or calling `reset!` invalidates the
+cache automatically.
+
+The `auto_discover(dir, pattern:)` method scans a directory for rule files:
+
+[source,ruby]
+----
+registry.auto_discover("lib/rules/", pattern: "**/*_rule.rb")
+----
+
+=== Profile
+
+`Lutaml::Model::Validation::Profile` selects which rules run during validation.
+Profiles are loaded from YAML and support import-based composition.
+
+`Profile.load(path)` validates the YAML structure — it raises `ArgumentError`
+if the file does not contain a `name` string key.
+
+[source,yaml]
+----
+# profiles/basic.yml
+name: basic
+description: Basic validation
+rules:
+  - RequiredFieldsRule
+  - StyleReferencesRule
+----
+
+[source,yaml]
+----
+# profiles/strict.yml
+name: strict
+import:
+  - basic
+rules:
+  - BookmarksRule
+  - ImagesRule
+----
+
+[source,ruby]
+----
+registry = Lutaml::Model::Validation.new_registry
+registry.register(RequiredFieldsRule)
+registry.register(StyleReferencesRule)
+registry.register(BookmarksRule)
+registry.register(ImagesRule)
+
+basic = Lutaml::Model::Validation::Profile.load("profiles/basic.yml")
+strict = Lutaml::Model::Validation::Profile.load("profiles/strict.yml")
+
+# Resolve a profile to get rule instances
+profiles = { "basic" => basic, "strict" => strict }
+rules = strict.resolve(registry, profiles)
+# => [RequiredFieldsRule, StyleReferencesRule, BookmarksRule, ImagesRule]
+
+# Circular imports are detected and raise ArgumentError
+# profile_a imports profile_b, profile_b imports profile_a => ArgumentError
+----
+
+=== Context
+
+`Lutaml::Model::Validation::Context` provides mutable error accumulation and
+per-rule state, useful for streaming or multi-pass validation.
+
+[source,ruby]
+----
+context = Lutaml::Model::Validation::Context.new
+context.add_error(issue)
+context.add_errors([issue1, issue2])
+context.errors  # => [issue, issue1, issue2]
+
+# Per-rule state for accumulation during streaming
+state = context.rule_state("DOC-010")
+state[:count] = (state[:count] || 0) + 1
+
+context.reset!  # Clear all errors and state
+----
+
+=== Report and LayerResult
+
+`Lutaml::Model::Validation::Report` and `LayerResult` are serializable report
+models for structured validation output.
+
+[source,ruby]
+----
+issue = Lutaml::Model::Validation::Issue.new(
+  severity: "error", code: "DOC-001", message: "Missing title"
+)
+layer = Lutaml::Model::Validation::LayerResult.new(
+  name: "Structure", status: "fail", duration_ms: 15, issues: [issue]
+)
+report = Lutaml::Model::Validation::Report.new(
+  source: "document.docx", valid: false, duration_ms: 150, layers: [layer]
+)
+
+report.issues   # => [issue]
+report.errors   # => [issue]
+report.warnings # => []
+report.to_json  # Full JSON serialization
+----
+
+=== Remediation
+
+`Lutaml::Model::Validation::Remediation` is an abstract base class for
+auto-fix logic. Override `id`, `targets`, `applicable?`, `fix`, and `preview`.
+
+NOTE: The base `fix` method raises `NotImplementedError`. You must override
+it in your subclass.
+
+[source,ruby]
+----
+class FixBrokenReferences < Lutaml::Model::Validation::Remediation
+  def id = "REM-001"
+  def targets = ["DOC-020"]
+
+  def applicable?(_context, report)
+    report.any? { |i| i.code == "DOC-020" }
+  end
+
+  def fix(context, report)
+    # Apply fixes
+    Lutaml::Model::Validation::RemediationResult.new(
+      success: true,
+      message: "Fixed 3 broken references",
+      fixed_codes: ["DOC-020"]
+    )
+  end
+
+  def preview(context, report)
+    # Dry-run (optional)
+    "Will fix 3 broken references"
+  end
+end
+----
+
+== Running validation
+
+=== Return issues array
+
+[source,ruby]
+----
+issues = Lutaml::Model::Validation.validate(context_hash, registry)
+issues.each do |issue|
+  puts "[#{issue.severity}] #{issue.code}: #{issue.message}"
+end
+----
+
+=== Raise on errors
+
+[source,ruby]
+----
+begin
+  Lutaml::Model::Validation.validate!(context_hash, registry)
+rescue Lutaml::Model::Validation::ValidationError => e
+  puts e.message  # => "[DOC-001] Missing title\n[DOC-020] Broken reference"
+  e.issues        # => [#<Issue code="DOC-001">, #<Issue code="DOC-020">]
+end
+----
+
+`ValidationError` exposes an `issues` accessor containing the error-severity
+issues that triggered the exception.
+
+`validate!` raises only for `error` severity issues. Warnings, info, and notice
+issues are returned silently.
+
+=== With profiles
+
+[source,ruby]
+----
+issues = Lutaml::Model::Validation.validate(context, registry, profile: profile)
+----
+
+== Design principles
+
+* **Open/Closed**: Extend by subclassing Rule and Remediation, not by modifying framework code.
+* **Instance-based Registry**: Multiple registries can coexist for different validation contexts.
+* **Serializable**: Issue, Report, and RemediationResult serialize to JSON via lutaml-model.
+* **Composable Profiles**: YAML profiles with import resolution for rule reuse.
+* **Orthogonal**: Works alongside existing attribute validation, not replacing it.

data/docs/_guides/index.adoc

@@ -33,6 +33,7 @@ Task-oriented guides for accomplishing specific goals with Lutaml::Model.
 * link:../liquid-templates[Liquid Templates] - Template integration
 * link:../ooxml-examples[OOXML Examples] - Real-world Office Open XML
 * link:../consolidation-mapping[Consolidation Mapping] - Group sibling elements into structured models
+* link:../document-validation[Document Validation] - Document-level validation with rules, profiles, and remediation
 
 == By task
 

data/docs/_guides/xml-mapping.adoc

@@ -307,7 +307,8 @@ end
 ====
 When a model has `mixed_content`, use `map_content` with `collection: true`
 to capture the multiple text segments between child elements.
-Without `collection: true`, only the first (or last) text segment is captured.
+Without `collection: true`, a `MixedContentCollectionError` is raised at
+finalization time.
 ====
 
 .Complete round-trip with `mixed_content` and `map_content collection: true`
@@ -496,6 +497,13 @@ Use `ordered` when:
 
 Use `sequence` when you need strict order validation (see <<Sequence patterns>>).
 
+[IMPORTANT]
+====
+`ordered` models element-only content -- `map_content` is not allowed.
+If you need to capture text content between elements, use `mixed_content`
+instead (see <<mixed-content>>).
+====
+
 Syntax:
 
 [source,ruby]

data/docs/_guides/xml_mappings/07_best_practices.adoc

@@ -324,6 +324,42 @@ end
 
 == Mixed content practices
 
+=== Do not use `map_content` with `ordered` (element-only content)
+
+The `ordered` method means element-only content -- text nodes are not modeled.
+Using `map_content` with `ordered` raises `OrderedContentMappingError`.
+If you need text between elements, use `mixed_content` instead.
+
+**Don't:**
+
+[source,ruby]
+----
+class Paragraph < Lutaml::Model::Serializable
+  attribute :text, :string
+
+  xml do
+    element 'p'
+    ordered  # Element-only -- no text content allowed
+    map_content to: :text  # ERROR: OrderedContentMappingError
+  end
+end
+----
+
+**Do:**
+
+[source,ruby]
+----
+class Paragraph < Lutaml::Model::Serializable
+  attribute :text, :string, collection: true
+
+  xml do
+    element 'p'
+    mixed_content  # Allows text + elements
+    map_content to: :text
+  end
+end
+----
+
 === Always declare `mixed_content` for elements with interleaved text and children
 
 When an XML element contains both text nodes and child elements in arbitrary

data/docs/_guides/xml_mappings/08_troubleshooting.adoc

@@ -8,6 +8,95 @@ parent: XML Mappings Guide
 
 == Common errors
 
+=== OrderedContentMappingError
+
+**Error message:**
+
+----
+Lutaml::Model::OrderedContentMappingError: Element-only content model
+(`ordered`) does not support `map_content` in ModelName. Use `mixed_content`
+instead of `ordered` when you need to capture text content between elements.
+----
+
+**Cause:**
+
+Using `map_content` (text content mapping) together with `ordered`
+(element-only content model). Element-only models only contain child elements,
+not text nodes.
+
+**Solution:**
+
+If you need text content between elements, use `mixed_content` instead of
+`ordered`:
+
+[source,ruby]
+----
+# WRONG -- ordered + map_content is invalid
+class Paragraph < Lutaml::Model::Serializable
+  xml do
+    element 'p'
+    ordered  # Element-only, no text allowed
+    map_content to: :text  # ERROR!
+  end
+end
+
+# CORRECT -- use mixed_content for text + elements
+class Paragraph < Lutaml::Model::Serializable
+  attribute :text, :string, collection: true
+
+  xml do
+    element 'p'
+    mixed_content  # Allows text + elements
+    map_content to: :text  # OK!
+  end
+end
+----
+
+=== MixedContentCollectionError
+
+**Error message:**
+
+----
+Lutaml::Model::MixedContentCollectionError: Mixed content requires `text`
+to be a string collection in ModelName. Use `attribute :text, :string,
+collection: true` when `mixed_content` is enabled.
+----
+
+**Cause:**
+
+Using `mixed_content` with `map_content` mapped to a non-collection attribute.
+Mixed content produces multiple text segments (one between each pair of child
+elements), so the target attribute must be a collection.
+
+**Solution:**
+
+Declare the attribute with `collection: true`:
+
+[source,ruby]
+----
+# WRONG -- non-collection attribute with mixed content
+class Paragraph < Lutaml::Model::Serializable
+  attribute :text, :string  # Missing collection: true
+
+  xml do
+    element 'p'
+    mixed_content
+    map_content to: :text  # ERROR!
+  end
+end
+
+# CORRECT -- collection attribute for mixed content
+class Paragraph < Lutaml::Model::Serializable
+  attribute :text, :string, collection: true
+
+  xml do
+    element 'p'
+    mixed_content
+    map_content to: :text  # OK!
+  end
+end
+----
+
 === NoRootMappingError
 
 **Error message:**

data/docs/_tutorials/lutaml-xml-architecture.adoc

@@ -690,7 +690,8 @@ XmlElement = {
   attributes: { orderDate: "1999-10-20" },
   elements: [
     XmlElement(name: "shipTo", ...),
-    XmlText("Text content")
+    XmlText("Text content"),
+    XmlComment(" comment text ")
   ],
   content: "Text content",  # For mixed content
 }
@@ -705,6 +706,10 @@ XmlText = {
   content: "Text content",
   namespace: nil,  # or NamespaceClass
 }
+
+XmlComment = {
+  content: " comment text ",  # Content between <!-- and -->
+}
 ```
 
 **Key Properties**:

data/lib/lutaml/model/attribute.rb

@@ -330,7 +330,25 @@ module Lutaml
 
       def default(register = Lutaml::Model::Config.default_register,
 instance_object = nil)
-        cast_value(default_value(register, instance_object), register)
+        if instance_object.nil?
+          @default_cache ||= {}
+          cached = @default_cache[register]
+          return cached if cached
+
+          result = cast_value(default_value(register, nil), register)
+          if immutable_value?(result)
+            @default_cache[register] = result
+          end
+          result
+        else
+          cast_value(default_value(register, instance_object), register)
+        end
+      end
+
+      def immutable_value?(value)
+        value.nil? || value.is_a?(Numeric) || value.is_a?(String) ||
+          value.is_a?(Symbol) || value == true || value == false ||
+          value.frozen?
       end
 
       def default_value(register, instance_object = nil)

data/lib/lutaml/model/error/liquid_drop_already_registered_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    class LiquidDropAlreadyRegisteredError < Error
+      def initialize(drop_class_name)
+        super("Liquid drop class '#{drop_class_name}' is already registered.")
+      end
+    end
+  end
+end

data/lib/lutaml/model/error/ordered_content_mapping_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    class OrderedContentMappingError < Error
+      def initialize(model_class)
+        @model_class = model_class
+        super()
+      end
+
+      def to_s
+        "Element-only content model (`ordered`) does not support `map_content` in #{@model_class}. " \
+          "Use `mixed_content` instead of `ordered` when you need to capture text content between elements."
+      end
+    end
+  end
+end

data/lib/lutaml/model/global_context.rb

@@ -194,6 +194,7 @@ module Lutaml
       def clear_caches
         @resolver.clear_all_caches
         Register.clear_resolve_cache
+        Transform.clear_cache!
       end
 
       # =====================================================================

data/lib/lutaml/model/liquefiable.rb

@@ -36,7 +36,8 @@ module Lutaml
         def register_liquid_drop_class
           validate_liquid!
           if base_drop_class
-            raise "#{drop_class_name} Already exists!"
+            raise Lutaml::Model::LiquidDropAlreadyRegisteredError,
+                  drop_class_name
           end
 
           const_set(drop_class_name,
@@ -45,6 +46,14 @@ module Lutaml
                         super()
                         @object = object
                       end
+
+                      def liquefy_value(value)
+                        if value.is_a?(Array)
+                          value.map(&:to_liquid)
+                        else
+                          value.to_liquid
+                        end
+                      end
                     end)
         end
 
@@ -99,13 +108,7 @@ module Lutaml
           return if base_drop_class.method_defined?(method_name)
 
           base_drop_class.define_method(method_name) do
-            value = @object.public_send(method_name)
-
-            if value.is_a?(Array)
-              value.map(&:to_liquid)
-            else
-              value.to_liquid
-            end
+            liquefy_value(@object.public_send(method_name))
           end
         end
 
@@ -114,13 +117,7 @@ module Lutaml
 
           liquid_mappings.mappings.each do |key, method_name|
             base_drop_class.define_method(key) do
-              value = @object.public_send(method_name)
-
-              if value.is_a?(Array)
-                value.map(&:to_liquid)
-              else
-                value.to_liquid
-              end
+              liquefy_value(@object.public_send(method_name))
             end
           end
         end

data/lib/lutaml/model/mapping/mapping_rule.rb

@@ -81,6 +81,10 @@ module Lutaml
         @polymorphic_map = polymorphic_map
         @transform = transform
 
+        # Cache whether this rule needs the full deserialize chain.
+        # Over 95% of rules are "simple" (no custom method, no delegate).
+        @needs_full_deserialize = has_custom_method_for_deserialization? || !!delegate
+
         # Only calculate default_value_map if value_map is not fully provided
         if value_map.empty? || !value_map[:from] || !value_map[:to]
           # Build value_map by starting with defaults from render_nil/render_empty,
@@ -280,9 +284,13 @@ module Lutaml
       end
 
       def deserialize(model, value, attributes, mapper_class = nil)
-        handle_custom_method(model, value, mapper_class) ||
-          handle_delegate(model, value, attributes) ||
+        if @needs_full_deserialize
+          handle_custom_method(model, value, mapper_class) ||
+            handle_delegate(model, value, attributes) ||
+            handle_transform_method(model, value, attributes)
+        else
           handle_transform_method(model, value, attributes)
+        end
       end
 
       def has_custom_method_for_serialization?

data/lib/lutaml/model/mapping_hash.rb

@@ -3,7 +3,7 @@
 module Lutaml
   module Model
     class MappingHash < ::Hash
-      attr_accessor :ordered, :node
+      attr_accessor :ordered, :node, :attribute_order
 
       def initialize
         @ordered = false