lutaml-model 0.8.3 → 0.8.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ae1d87545b35bb4c5611ee8063e4ac7529f91b100b4505c7b2f2f8e0815ca07
-  data.tar.gz: 9c3784b872d6bfed995de44cfcde258c20f6c7004a6e0663332b44c1be653751
+  metadata.gz: 2bc036758cf2a4ac1420e14fc6be130730410ab183cd002ced260bdbf08793eb
+  data.tar.gz: 1dfc1b473558992eb1481a535d86c1688313951530762c9317af90413028032e
 SHA512:
-  metadata.gz: 0130ba36bc10f0fc1791433cd9d7ac7724920f2aa5023042aa4e24480d87cd75f342fc98510fc2dc3da67d67b491c8d0c07ce705819140c6ff989681dbf700e9
-  data.tar.gz: 0ddc770da4f35d7dffea4219f4663e5cbc56cd19d9ffd8b3396c8b7e7419a20c2491e84dfcc419de71a5b8fc1fbf43abb9d434a4c1d9f4878cc521e672ca65cd
+  metadata.gz: 8a4cec37c9acf840b89f6f363aecb8e7bf1a2237d962c6fa8bbe4d4422848cc63812efbd86369780c0e7d26470ff9f220284d062af86b9ebf7f621f3f8e579cb
+  data.tar.gz: a48c77e4d99c97fb8cc6fa6793a45b2ba12b79196d9340a23bf4d43a1090c84c05a2402a84ab52792b105713c78caa51f58cfcb141cf79459b06c929adac11b5

data/.github/workflows/dependent-tests.yml

@@ -19,6 +19,8 @@ on:
 
 jobs:
   rake:
-    uses: metanorma/ci/.github/workflows/dependent-rake.yml@main
+    uses: metanorma/ci/.github/workflows/dependent-rake.yml@fix/add-pat-token
     with:
       command: bundle exec rspec
+    secrets:
+      pat_token: ${{ secrets.LUTAML_CI_PAT_TOKEN }}

data/.rubocop.yml

@@ -24,3 +24,21 @@ Style/OneClassPerFile:
       - Exclude
   Exclude:
     - 'spec/**/*'
+
+RSpec/EmptyExampleGroup:
+  inherit_mode:
+    merge:
+      - Exclude
+  Exclude:
+    - 'spec/lutaml/jsonld/transform_spec.rb'
+
+RSpec/NamedSubject:
+  inherit_mode:
+    merge:
+      - Exclude
+  Exclude:
+    - 'spec/lutaml/turtle/transform_spec.rb'
+
+RSpec/ContextMethod:
+  Exclude:
+    - 'spec/lutaml/jsonld/transform_spec.rb'

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 13:11:11 UTC using RuboCop version 1.86.1.
 # 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: 3264
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
@@ -118,7 +110,7 @@ Lint/UselessConstantScoping:
     - 'lib/lutaml/xml/adapter/nokogiri_adapter.rb'
     - 'lib/lutaml/xml/mapping_rule.rb'
 
-# Offense count: 340
+# Offense count: 355
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
@@ -134,23 +126,23 @@ Metrics/BlockLength:
 Metrics/BlockNesting:
   Max: 6
 
-# Offense count: 301
+# Offense count: 315
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 551
+# Offense count: 575
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 514
 
-# Offense count: 85
+# Offense count: 88
 # Configuration parameters: CountKeywordArgs.
 Metrics/ParameterLists:
   Max: 24
   MaxOptionalParameters: 5
 
-# Offense count: 255
+# Offense count: 264
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
@@ -242,7 +234,7 @@ RSpec/BeforeAfterAll:
 RSpec/ContextWording:
   Enabled: false
 
-# Offense count: 81
+# Offense count: 92
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
@@ -253,7 +245,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: 1234
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 68
@@ -328,11 +320,11 @@ RSpec/MultipleDescribes:
     - 'spec/lutaml/xml/namespace_resolution_strategy_spec.rb'
     - 'spec/lutaml/xml/xml_space_type_spec.rb'
 
-# Offense count: 1336
+# Offense count: 1442
 RSpec/MultipleExpectations:
   Max: 21
 
-# Offense count: 189
+# Offense count: 190
 # Configuration parameters: AllowSubject.
 RSpec/MultipleMemoizedHelpers:
   Max: 15
@@ -376,13 +368,13 @@ RSpec/RepeatedExampleGroupDescription:
   Exclude:
     - 'spec/lutaml/model/mixed_content_spec.rb'
 
-# Offense count: 32
+# Offense count: 40
 # 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 +385,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 +393,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/Gemfile

@@ -12,6 +12,7 @@ gem "base64"
 gem "benchmark-ips"
 gem "bigdecimal"
 gem "canon" # , path: "../canon"
+gem "json-ld", "~> 3.3"
 gem "liquid", "~> 5"
 gem "multi_json"
 gem "nokogiri"
@@ -20,6 +21,7 @@ gem "oj"
 gem "openssl", "~> 3.0"
 gem "ox"
 gem "rake"
+gem "rdf-turtle", "~> 3.3"
 gem "rexml"
 gem "rspec"
 gem "rubocop"

data/README.adoc

@@ -27,7 +27,7 @@ for:
 
 It provides simple, flexible and comprehensive mechanisms for defining
 information models with attributes and types, and the serialization of them
-to/from serialization formats including JSON, XML, YAML, and TOML, as well as
+to/from serialization formats including JSON, XML, YAML, TOML, JSON-LD, and Turtle, as well as
 transformation to other formats like Hash.
 
 For serialization formats, it uses an adapter pattern to support multiple
@@ -48,7 +48,7 @@ link:docs/migration-guides/0-1-0-migrate-from-shale.adoc[Migrating from Shale to
 == Features
 
 * Define models with attributes and types
-* Serialize and deserialize models to/from JSON, XML, YAML, and TOML
+* Serialize and deserialize models to/from JSON, XML, YAML, TOML, JSON-LD, and Turtle
 * Transform models to other formats like Hash
 * Support for multiple serialization libraries (e.g., `toml-rb`, `tomlib`)
 * Configurable adapters for different serialization formats
@@ -65,7 +65,9 @@ link:docs/migration-guides/0-1-0-migrate-from-shale.adoc[Migrating from Shale to
 * Symmetric OOP architecture for all formats with KeyValueDataModel (see <<keyvaluedatamodel-architecture>>)
 * Parse XSD schemas into Ruby objects for inspection and manipulation (see <<xsd-schema-parsing>>)
 * Reusable XML mapping classes for sharing mappings across models
+* RDF namespace classes and JSON-LD/Turtle format adapters for Linked Data serialization
 * 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
@@ -5390,6 +5392,11 @@ Collection serialization formats::
 `jsonl`::: JSONL (JSON Lines) (see <<mapping-collections>>)
 `yamls`::: YAML Stream (multi-document format) (see <<mapping-collections>>)
 
+RDF serialization formats::
+
+`rdf`::: Unified RDF mapping for both JSON-LD and Turtle (see <<mapping-rdf>>)
+`turtle`::: Turtle (see link:docs/_guides/turtle-serialization.adoc[Turtle Serialization])
+
 
 .Using the `xml`, `hsh`, `json`, `yaml`, `toml` and `key_value` blocks to define serialization mappings
 [example]
@@ -5438,6 +5445,73 @@ end
 ====
 
 
+[[mapping-rdf]]
+=== Unified RDF mapping (`rdf`)
+
+The `rdf` block defines predicate-based mappings once for both JSON-LD and
+Turtle serialization. It follows the same unified-mapping principle as
+`key_value` (which serves JSON, YAML, TOML).
+
+.Using the `rdf` block to define unified RDF mappings
+[example]
+====
+[source,ruby]
+----
+class Concept < Lutaml::Model::Serializable
+  attribute :code, :string
+  attribute :name, :string
+
+  rdf do
+    namespace SkosNamespace
+
+    subject { |m| "http://example.org/concept/#{m.code}" }
+    type "skos:Concept"
+
+    predicate :notation,  namespace: SkosNamespace, to: :code
+    predicate :prefLabel, namespace: SkosNamespace, to: :name
+  end
+end
+----
+
+Serializes to both formats:
+
+[source,ruby]
+----
+concept = Concept.new(code: "2119", name: "component")
+concept.to_turtle   # => Turtle with @prefix, a skos:Concept, predicates
+concept.to_jsonld   # => JSON-LD with @context, @type, @id, properties
+----
+====
+
+Graph-level serialization uses `members` to emit all contained resources as
+separate subjects in the same document:
+
+[source,ruby]
+----
+class Vocabulary < Lutaml::Model::Serializable
+  attribute :id, :string
+  attribute :concepts, Concept, collection: true
+
+  rdf do
+    namespace SkosNamespace
+    subject { |v| "http://example.org/vocab/#{v.id}" }
+    type "skos:ConceptScheme"
+    predicate :prefLabel, namespace: SkosNamespace, to: :id
+    members :concepts
+  end
+end
+
+# Turtle: single document with ConceptScheme + all Concept triples
+# JSON-LD: @graph array with ConceptScheme + all Concept objects
+vocab.to_turtle
+vocab.to_jsonld
+----
+
+See link:docs/_guides/rdf-serialization.adoc[Unified RDF Serialization] for the
+complete guide including language-tagged values, graph serialization, and
+architecture details.
+
+
 == Serialization: XML
 
 === General
@@ -6349,7 +6423,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 +6573,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 +6678,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.
 
@@ -10046,8 +10173,14 @@ Key-value data models supported are identified by their short name:
 `json`:: JSON
 `yaml`:: YAML
 `toml`:: TOML
+`jsonld`:: JSON-LD (extends key-value with `@context`, `@type`, `@id`)
 `key_value`:: A way to configure key-value mappings for all supported key-value data models.
 
+RDF serialization formats::
+
+`rdf`:: Unified RDF mapping for both JSON-LD and Turtle (see <<mapping-rdf>>)
+`turtle`:: Turtle (see link:docs/_guides/turtle-serialization.adoc[Turtle Serialization])
+
 
 === Mapping
 
@@ -15681,6 +15814,8 @@ LutaML, out of the box, supports the following serialization formats:
 * YAML (https://yaml.org/[YAML version 1.2])
 * JSON (https://www.ecma-international.org/publications-and-standards/standards/ecma-404/[ECMA-404 The JSON Data Interchange Standard], unofficial link: https://www.json.org[JSON])
 * TOML (https://toml.io/en[TOML version 1.0])
+* JSON-LD (https://www.w3.org/TR/json-ld11/[W3C JSON-LD 1.1])
+* Turtle (https://www.w3.org/TR/turtle/[W3C RDF 1.1 Turtle])
 
 The adapter interface is also used to support certain transformation of models
 into an "end format", which is not a serialization format. For example, the
@@ -15923,6 +16058,37 @@ end
 ----
 
 
+=== JSON-LD
+
+Lutaml::Model supports serialization to and from JSON-LD (W3C JSON-LD 1.1).
+JSON-LD is a key-value format that extends JSON with `@context`, `@type`, and
+`@id`. No additional gem is required beyond `lutaml-model`.
+
+For unified RDF mapping (both JSON-LD and Turtle from a single `rdf` block), see
+link:docs/_guides/rdf-serialization.adoc[Unified RDF Serialization].
+
+See link:docs/_guides/jsonld-serialization.adoc[JSON-LD Serialization] for the
+legacy `jsonld do` block DSL and usage examples.
+
+
+=== Turtle
+
+Lutaml::Model supports serialization to and from W3C RDF Turtle format.
+Turtle is a non-key-value format based on RDF triples. Requires the
+`rdf-turtle` gem:
+
+[source,ruby]
+----
+gem "rdf-turtle", "~> 3.3"
+----
+
+For unified RDF mapping (both JSON-LD and Turtle from a single `rdf` block), see
+link:docs/_guides/rdf-serialization.adoc[Unified RDF Serialization].
+
+See link:docs/_guides/turtle-serialization.adoc[Turtle Serialization] for the
+legacy `turtle do` block DSL and usage examples.
+
+
 === Per-operation adapter override
 
 Override the adapter for a single serialization/deserialization call using the `adapter:` option:
@@ -16938,6 +17104,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