lutaml-model 0.8.2 → 0.8.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6eb717e543e98728e8819eef97823780156ce2f594c360f678b9d23f9baf230
-  data.tar.gz: 64906eed0282afa83f0905db2e3a75e607a22bacf5e9e40cafa3c0007bdc8fec
+  metadata.gz: c512d678682ea756cb7eb7a3d439a7d511b763405936e598900f42f7f07aa705
+  data.tar.gz: e6623585797f809090619a9e6268e026773d962cac0f940ccae608627d8e714c
 SHA512:
-  metadata.gz: 62b3ca87767a8b942d78b22800b6765467532a194484c18f494bc29ff558adb57f2fcf92f7ea5e2bba5a05cac811c39d807c40885c247190452b33556ccf78f8
-  data.tar.gz: 1771fd424b8c31e9da2c6940b750c80af2ac38b4ae05e02d234894ee9df5cd5ad4dbd6a9486bbbee0060a3f956507a98a3bfdcc6dd1d6a074957f544649638ee
+  metadata.gz: 81558e237a6a7f55c3defee45c8fa8a1d59bf75a875159708065ce8db44308fdaa17d3c727d6ff1074477391ec199008088221f54d5bbb7f2b3b4546ff4d25cf
+  data.tar.gz: 242730ac59628f328fe07409cc54d7798e75b40d29b6b47ad7382de37a033d9f907d0578d8ab950c45c9ff1b06cd67f6cb98e3e6215948149e63e8e4591be15d

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-05-03 22:38:22 UTC using RuboCop version 1.86.1.
+# on 2026-05-06 04:21:39 UTC using RuboCop version 1.86.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -11,15 +11,7 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'lutaml-model.gemspec'
 
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowForAlignment.
-Layout/CommentIndentation:
-  Exclude:
-    - 'lib/lutaml/model/mapping/listener.rb'
-    - 'lib/lutaml/model/services/base.rb'
-
-# Offense count: 3210
+# Offense count: 3232
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
@@ -42,10 +34,16 @@ Lint/ConstantDefinitionInBlock:
 Lint/DuplicateBranch:
   Enabled: false
 
-# Offense count: 3
+# Offense count: 22
 Lint/DuplicateMethods:
   Exclude:
     - 'lib/lutaml/xml/mapping.rb'
+    - 'spec/lutaml/model/liquid_compatibility_spec.rb'
+    - 'spec/lutaml/xml/namespace_no_hoisting_spec.rb'
+    - 'spec/lutaml/xml/namespace_scope_declare_spec.rb'
+    - 'spec/lutaml/xml/namespace_scope_vcard_spec.rb'
+    - 'spec/lutaml/xml/prefix_control_spec.rb'
+    - 'spec/lutaml/xml/type_namespace_examples_spec.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
@@ -118,7 +116,7 @@ Lint/UselessConstantScoping:
     - 'lib/lutaml/xml/adapter/nokogiri_adapter.rb'
     - 'lib/lutaml/xml/mapping_rule.rb'
 
-# Offense count: 340
+# Offense count: 346
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
@@ -134,23 +132,23 @@ Metrics/BlockLength:
 Metrics/BlockNesting:
   Max: 6
 
-# Offense count: 301
+# Offense count: 309
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 551
+# Offense count: 562
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 514
 
-# Offense count: 85
+# Offense count: 86
 # Configuration parameters: CountKeywordArgs.
 Metrics/ParameterLists:
   Max: 24
   MaxOptionalParameters: 5
 
-# Offense count: 255
+# Offense count: 260
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
@@ -242,7 +240,7 @@ RSpec/BeforeAfterAll:
 RSpec/ContextWording:
   Enabled: false
 
-# Offense count: 81
+# Offense count: 88
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
@@ -253,7 +251,7 @@ RSpec/DescribeMethod:
     - 'spec/lutaml/xml/schema/xsd/schema_helper_methods_spec.rb'
     - 'spec/lutaml/xml/serializable_namespace_spec.rb'
 
-# Offense count: 1164
+# Offense count: 1207
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 68
@@ -328,11 +326,11 @@ RSpec/MultipleDescribes:
     - 'spec/lutaml/xml/namespace_resolution_strategy_spec.rb'
     - 'spec/lutaml/xml/xml_space_type_spec.rb'
 
-# Offense count: 1336
+# Offense count: 1383
 RSpec/MultipleExpectations:
   Max: 21
 
-# Offense count: 189
+# Offense count: 190
 # Configuration parameters: AllowSubject.
 RSpec/MultipleMemoizedHelpers:
   Max: 15
@@ -376,13 +374,13 @@ RSpec/RepeatedExampleGroupDescription:
   Exclude:
     - 'spec/lutaml/model/mixed_content_spec.rb'
 
-# Offense count: 32
+# Offense count: 35
 # Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata, InflectorPath, EnforcedInflector.
 # SupportedInflectors: default, active_support
 RSpec/SpecFilePathFormat:
   Enabled: false
 
-# Offense count: 31
+# Offense count: 32
 # Configuration parameters: IgnoreNameless, IgnoreSymbolicNames.
 RSpec/VerifiedDoubles:
   Exclude:
@@ -393,6 +391,7 @@ RSpec/VerifiedDoubles:
     - 'spec/lutaml/model/schema/renderer_spec.rb'
     - 'spec/lutaml/model/transformation_builder_spec.rb'
     - 'spec/lutaml/model/transformation_spec.rb'
+    - 'spec/lutaml/model/validation/context_spec.rb'
     - 'spec/lutaml/xml/namespace_resolution_strategy_spec.rb'
 
 # Offense count: 1
@@ -400,13 +399,14 @@ Security/MarshalLoad:
   Exclude:
     - 'scripts-xmi-profile/profile_xmi.rb'
 
-# Offense count: 1
+# Offense count: 2
 # This cop supports unsafe autocorrection (--autocorrect-all).
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 # AllowedMethods: ==, equal?, eql?
 Style/ClassEqualityComparison:
   Exclude:
     - 'lib/lutaml/model/attribute.rb'
+    - 'lib/lutaml/model/validation/profile.rb'
 
 # Offense count: 13
 # This cop supports safe autocorrection (--autocorrect).

data/README.adoc

@@ -66,6 +66,7 @@ link:docs/migration-guides/0-1-0-migrate-from-shale.adoc[Migrating from Shale to
 * Parse XSD schemas into Ruby objects for inspection and manipulation (see <<xsd-schema-parsing>>)
 * Reusable XML mapping classes for sharing mappings across models
 * Consolidation mapping: group sibling XML elements into structured model instances (see <<consolidation-mapping>>)
+* Document-level validation framework with composable rules, profiles, and remediation (see <<document-validation-framework>>)
 
 
 == Data modeling in a nutshell
@@ -6349,7 +6350,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`
@@ -6498,6 +6500,51 @@ Without `mixed_content`, serialization groups all text first then all elements
 (or vice versa), losing the original interleaving. This is the most common
 cause of XML round-trip failures in document-processing applications.
 
+===== XML Comment round-trip preservation
+
+XML comments (`<!-- ... -->`) are preserved during round-trip serialization
+in `mixed_content` and `ordered` modes. Comments appear in `element_order`
+as entries with `node_type: :comment` and are reconstructed during output.
+
+.Comment round-trip in mixed content
+[example]
+====
+[source,ruby]
+----
+class Paragraph < Lutaml::Model::Serializable
+  attribute :content, :string, collection: true
+
+  xml do
+    element 'p'
+    mixed_content
+    map_content to: :content
+  end
+end
+----
+
+Input XML with a comment between text and an element:
+
+[source,xml]
+----
+<p>Text before<!-- a comment --> text after</p>
+----
+
+[source,ruby]
+----
+parsed = Paragraph.from_xml(xml)
+parsed.element_order
+# => [#<Lutaml::Xml::Element type: "Text", node_type: :text>,
+#     #<Lutaml::Xml::Element type: "Comment", node_type: :comment, text_content: " a comment ">,
+#     #<Lutaml::Xml::Element type: "Text", node_type: :text>]
+
+parsed.to_xml
+# => "<p>Text before<!-- a comment --> text after</p>"
+----
+====
+
+NOTE: Comments are tracked in `element_order` but are **not** included in
+model attributes or the parsed hash. They exist solely for serialization fidelity.
+
 ==== (DEPRECATED) Mixed content declaration (`root` method with `mixed:`)
 
 To map this to Lutaml::Model we can use the `mixed` option in either way:
@@ -6558,6 +6605,13 @@ preserves the order of **XML Elements and Content**.
 
 NOTE: When both options are used, `mixed: true` takes precedence.
 
+[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>>).
+====
+
 To specify ordered content, the `ordered: true` option needs to be set at the
 `xml` block's `root` method.
 
@@ -16938,6 +16992,164 @@ end
 For a complete architecture overview and migration guide from Register to
 GlobalContext, see link:docs/architecture.md[Architecture Documentation].
 
+[[document-validation-framework]]
+== Document Validation Framework
+
+Lutaml::Model provides a document-level validation framework (`Lutaml::Model::Validation`)
+for validating structural integrity, cross-references, and conformance against
+domain-specific rules. This is *orthogonal* to the existing attribute-level
+validation (`validate`/`validate!` on model instances) -- that validates type
+constraints, enumerations, and collections; this validates document-level concerns.
+
+=== Quick start
+
+[source,ruby]
+----
+require "lutaml/model/validation_framework"
+
+# 1. Define rules by subclassing Lutaml::Model::Validation::Rule
+class RequiredFieldsRule < Lutaml::Model::Validation::Rule
+  def code = "DOC-001"
+  def severity = "error"
+
+  def check(context)
+    missing = required_fields.select { |f| context[f].nil? || context[f].empty? }
+    missing.map { |f| issue("Missing required field: #{f}") }
+  end
+
+  private
+
+  def required_fields = %w[title author]
+end
+
+# 2. Register rules
+registry = Lutaml::Model::Validation.new_registry
+registry.register(RequiredFieldsRule)
+
+# 3. Run validation
+issues = Lutaml::Model::Validation.validate({ title: "Hello" }, registry)
+issues.each { |i| puts "[#{i.severity}] #{i.code}: #{i.message}" }
+# => [error] DOC-001: Missing required field: author
+
+# 4. Or raise on errors
+begin
+  Lutaml::Model::Validation.validate!({ title: "Hello" }, registry)
+rescue Lutaml::Model::Validation::ValidationError => e
+  puts e.message  # => "[DOC-001] Missing required field: author"
+  e.issues        # => [#<Issue code="DOC-001">]
+end
+----
+
+=== Core components
+
+[cols="1,4"]
+|===
+| Class | Purpose
+
+| `Validation::Issue`
+| Serializable issue with severity (`error`/`warning`/`info`/`notice`), code, message, location, line, suggestion
+
+| `Validation::Rule`
+| Abstract base class. Override `code`, `severity`, `category`, `applicable?`, and `check`
+
+| `Validation::Registry`
+| Instance-based rule registration with cached instantiation via `register`, `all`, `for_category`, `find`
+
+| `Validation::Profile`
+| YAML composable profiles with import resolution for rule subsets. `load` validates required `name` key
+
+| `Validation::Context`
+| Mutable context with error accumulation and per-rule state (for streaming validation)
+
+| `Validation::Report` / `LayerResult`
+| Serializable report models with aggregated severity filtering
+
+| `Validation::Remediation`
+| Abstract base for auto-fix logic. Subclass must override `fix` (raises `NotImplementedError` on base class)
+|===
+
+=== Composable profiles
+
+Profiles select *which* rules run, not *how* they run. They are loaded from YAML
+and support import-based composition.
+
+[source,yaml]
+----
+# profiles/basic.yml
+name: basic
+description: Basic DOCX 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")
+profiles = { "basic" => basic, "strict" => strict }
+
+rules = strict.resolve(registry, profiles)  # returns all 4 rule instances
+
+// Circular imports are detected and raise ArgumentError.
+// Profile YAML is validated: missing `name` key raises ArgumentError.
+----
+
+=== Remediation (auto-fix)
+
+Subclass `Validation::Remediation` to provide automatic fixes for specific issues:
+
+[source,ruby]
+----
+class FixBrokenReferences < Lutaml::Model::Validation::Remediation
+  def id = "REM-001"
+  def targets = ["DOC-020"]
+
+  def fix(context, report)
+    # ... apply fixes ...
+    Lutaml::Model::Validation::RemediationResult.new(
+      success: true,
+      message: "Fixed 3 broken references",
+      fixed_codes: ["DOC-020"]
+    )
+  end
+end
+----
+
+=== Relationship to attribute-level validation
+
+|===
+| Attribute validation (existing) | Document validation framework (new)
+
+| Validates model instance state (types, ranges, patterns)
+| Validates document-level concerns (structure, cross-references, conformance)
+
+| Runs during deserialization via `model.validate`
+| Runs on parsed documents against domain rules via `Validation.validate`
+
+| Returns `Array<Error>` error objects
+| Returns `Array<Issue>` serializable issue objects
+|===
+
+See link:docs/_pages/validation.adoc[Validation] for attribute-level validation details.
+
 
 == Comparison with Shale