lutaml-model 0.8.3 → 0.8.5

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

@@ -22,6 +22,17 @@ Task-oriented guides for accomplishing specific goals with Lutaml::Model.
 * link:../keyvalue-serialization[Key-Value Serialization] - JSON/YAML/TOML/Hash
 * link:../collection-serialization[Collection Serialization] - JSONL and YAML Stream
 
+== Linked Data serialization
+
+* link:../rdf-serialization[Unified RDF Serialization] - One `rdf` block for both JSON-LD and Turtle
+* link:../jsonld-serialization[JSON-LD Serialization] - W3C JSON-LD 1.1 with `@context`
+* link:../turtle-serialization[Turtle Serialization] - W3C RDF Turtle format
+
+== RDF infrastructure
+
+See link:../references/rdf-namespaces[RDF Namespaces] for namespace classes,
+`NamespaceSet`, `Iri`, and `Literal` value objects.
+
 == Advanced features
 
 * link:../value-transformations[Value Transformations] - Transform values during serialization
@@ -33,6 +44,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
 
@@ -48,6 +60,13 @@ Task-oriented guides for accomplishing specific goals with Lutaml::Model.
 . link:../value-transformations[Transform values if needed]
 . link:../missing-values-handling[Handle nil/empty values]
 
+=== I want to serialize to JSON-LD or Turtle (Linked Data)
+
+. link:../rdf-serialization[Unified RDF Serialization] (recommended — one block for both formats)
+. link:../jsonld-serialization[JSON-LD Serialization guide] (legacy `jsonld do` block)
+. link:../turtle-serialization[Turtle Serialization guide] (legacy `turtle do` block)
+. link:../references/rdf-namespaces[RDF Namespaces reference]
+
 === I want to work with collections
 
 . link:../collection-serialization[Collection Serialization]

data/docs/_guides/jsonld-serialization.adoc

@@ -0,0 +1,217 @@
+---
+title: JSON-LD Serialization
+nav_order: 15
+---
+
+= JSON-LD Serialization
+
+Lutaml::Model supports serialization to and from JSON-LD (W3C JSON-LD 1.1) using
+SKOS, Dublin Core Terms, and other W3C vocabularies.
+
+== Setup
+
+JSON-LD is built on the key-value serialization pipeline and requires no
+additional gems beyond what JSON already uses. The `json-ld` gem may be added
+for advanced JSON-LD Processing (expansion, compaction, flattening) in the
+future.
+
+JSON-LD is a **key-value** format adapter that extends the built-in key-value
+serialization with JSON-LD-specific constructs: `@context`, `@type`, and
+`@id`.
+
+== Mapping DSL
+
+Use the `jsonld do` block in your model to define JSON-LD mappings:
+
+[source,ruby]
+----
+class Concept < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :description, :string
+
+  jsonld do
+    context do
+      prefix Lutaml::Rdf::Namespaces::SkosNamespace
+      vocab "http://example.org/ns/"
+
+      term "name", id: "http://example.org/name"
+      term "description", id: "http://example.org/description"
+    end
+
+    type "skos:Concept"
+    id { |m| "http://example.org/concept/#{m.name}" }
+
+    map "name", to: :name
+    map "description", to: :description
+  end
+end
+----
+
+=== Context
+
+The `context` block builds the `@context` object in the JSON-LD output:
+
+* `prefix(NamespaceClass)` — registers an RDF namespace as a prefix
+* `vocab(uri)` — sets `@vocab` for unprefixed terms
+* `language(code)` — sets default `@language`
+* `base(uri)` — sets `@base` URI
+* `term(name, ...)` — defines a term with optional `id:`, `type:`,
+  `container:`, `language:`, `reverse:`
+
+Context resolution:
+
+* Compact IRIs (e.g., `"skos:Concept"`) are expanded to full URIs via prefix
+* Terms are resolved via the term definitions
+* Unprefixed names are resolved via `@vocab`
+
+=== Type and ID
+
+* `type "skos:Concept"` — sets `@type` in the output (resolved to full IRI via
+  context)
+* `id { |model| ... }` — generates `@id` from the model instance
+
+Both are optional. Omit `type` or `id` if your JSON-LD document does not
+require them.
+
+=== map
+
+`map` entries work identically to key-value serialization, defining the JSON
+properties serialized from model attributes.
+
+== Serialization
+
+[source,ruby]
+----
+concept = Concept.new(name: "test", description: "A test concept")
+jsonld = concept.to_jsonld
+----
+
+Produces:
+
+[source,json]
+----
+{
+  "@context": {
+    "skos": "http://www.w3.org/2004/02/skos/core#",
+    "@vocab": "http://example.org/ns/",
+    "name": "http://example.org/name",
+    "description": "http://example.org/description"
+  },
+  "@type": "http://www.w3.org/2004/02/skos/core#Concept",
+  "@id": "http://example.org/concept/test",
+  "name": "test",
+  "description": "A test concept"
+}
+----
+
+Nil attribute values are omitted from the output.
+
+== Deserialization
+
+[source,ruby]
+----
+concept = Concept.from_jsonld(jsonld_string)
+puts concept.name  # => "test"
+----
+
+The `from_jsonld` method:
+
+. Parses the JSON-LD string into a hash via `JSON.parse`
+. Strips all `@`-prefixed keywords (`@context`, `@type`, `@id`, `@graph`,
+  etc.) before attribute mapping
+. Delegates attribute mapping to the key-value transform pipeline
+
+This prevents JSON-LD keywords from colliding with model attributes named
+`type`, `id`, `context`, etc.
+
+== Round-trip
+
+Model data round-trips through JSON-LD serialization:
+
+[source,ruby]
+----
+restored = Concept.from_jsonld(concept.to_jsonld)
+restored.name == concept.name  # => true
+----
+
+The `@context` structure is preserved across round-trips because it is defined
+in the mapping, not derived from the input.
+
+== Unified `rdf` DSL
+
+If you need both JSON-LD and Turtle output from the same model, use the
+unified `rdf` DSL instead of separate `jsonld` and `turtle` blocks. This
+defines the mapping once and auto-generates `@context` from predicates:
+
+[source,ruby]
+----
+class Concept < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :code, :string
+
+  rdf do
+    namespace Lutaml::Rdf::Namespaces::SkosNamespace
+    subject { |m| "http://example.org/#{m.code}" }
+    type "skos:Concept"
+    predicate :prefLabel, namespace: SkosNamespace, to: :name
+    predicate :notation,  namespace: SkosNamespace, to: :code
+  end
+end
+----
+
+See link:../_guides/rdf-serialization.adoc[Unified RDF Serialization] for the
+complete guide including graph-level serialization with `members`.
+
+== Multi-format models
+
+A single model can define `json`, `jsonld`, `turtle`, and `rdf` mappings
+simultaneously. Each format operates independently:
+
+[source,ruby]
+----
+class Concept < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :code, :string
+
+  json do
+    map "name", to: :name
+    map "code", to: :code
+  end
+
+  rdf do
+    namespace Lutaml::Rdf::Namespaces::SkosNamespace
+    subject { |m| "http://example.org/#{m.code}" }
+    type "skos:Concept"
+    predicate :prefLabel, namespace: SkosNamespace, to: :name
+    predicate :notation,  namespace: SkosNamespace, to: :code
+  end
+end
+----
+
+* `to_json` produces plain JSON without `@context`
+* `to_jsonld` produces JSON-LD with auto-generated `@context`, `@type`, `@id`
+* `to_turtle` produces Turtle with `@prefix` declarations
+
+The unified `rdf` block creates mappings for both `:turtle` and `:jsonld`
+formats. If separate `jsonld do` or `turtle do` blocks are also defined, they
+take precedence over the `rdf` block for their respective format.
+
+== Error Handling
+
+* `JSON::ParserError` — raised for malformed JSON input
+* All parsing errors are wrapped in `Lutaml::Model::InvalidFormatError` by the
+  format pipeline
+
+== Architecture
+
+The JSON-LD format is composed of:
+
+* `Lutaml::JsonLd::Adapter` — extends `KeyValue::Document`; parses JSON-LD
+  strings to hashes and serializes hashes back to JSON
+* `Lutaml::JsonLd::Context` — DSL for building `@context` with prefixes,
+  vocab, terms, language, and base
+* `Lutaml::JsonLd::TermDefinition` — value object for term definitions with
+  `@id`, `@type`, `@container`, `@language`, `@reverse`
+* `Lutaml::JsonLd::Transform` — inherits from `Rdf::Transform`; auto-generates
+  `@context` from predicates, injects `@type`/`@id` on export, strips
+  `@`-keywords on import