lutaml-model 0.8.4 → 0.8.6

data/docs/_guides/turtle-serialization.adoc

@@ -0,0 +1,224 @@
+---
+title: Turtle Serialization
+nav_order: 16
+---
+
+= Turtle Serialization
+
+Lutaml::Model supports serialization to and from W3C RDF Turtle format using
+SKOS, Dublin Core Terms, and other W3C vocabularies.
+
+== Setup
+
+Add the `rdf-turtle` gem to your Gemfile:
+
+[source,ruby]
+----
+gem "rdf-turtle", "~> 3.3"
+----
+
+Turtle is a **non-key-value** format adapter with its own mapping DSL based on
+RDF triples (subject–predicate–object). It is registered as a first-class
+format in the `FormatRegistry` with dedicated `Mapping`, `Transform`, and
+`Adapter` classes.
+
+== Mapping DSL
+
+Use the `turtle do` block in your model to define Turtle mappings:
+
+[source,ruby]
+----
+class Concept < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :description, :string
+  attribute :code, :string
+
+  turtle do
+    namespace Lutaml::Rdf::Namespaces::SkosNamespace,
+              Lutaml::Rdf::Namespaces::DctermsNamespace
+
+    subject { |m| "http://example.org/concept/#{m.code}" }
+    type "skos:Concept"
+
+    predicate :prefLabel,
+              namespace: Lutaml::Rdf::Namespaces::SkosNamespace,
+              to: :name,
+              lang_tagged: true
+
+    predicate :definition,
+              namespace: Lutaml::Rdf::Namespaces::SkosNamespace,
+              to: :description
+
+    predicate :notation,
+              namespace: Lutaml::Rdf::Namespaces::SkosNamespace,
+              to: :code
+  end
+end
+----
+
+=== namespace
+
+Declares the `@prefix` lines in the output. Accepts one or more
+`Lutaml::Rdf::Namespace` subclass references. Internally builds a
+`NamespaceSet` for O(1) prefix lookup and IRI resolution.
+
+=== subject
+
+Required for top-level models with predicates and no `members`. A block that
+generates the subject URI from the model instance. Raises
+`Lutaml::Turtle::MissingSubjectError` if not defined when needed.
+
+Member models (serialized via a container's `members` declaration) can omit the
+`subject` block — blank nodes are used automatically.
+
+=== type
+
+Sets the RDF type (`rdf:type`) triple. Compact IRIs (e.g., `"skos:Concept"`)
+are resolved to full URIs via the declared namespaces. Full URIs (e.g.,
+`"http://example.org/MyType"`) are used as-is.
+
+=== predicate
+
+Each `predicate` creates a `Lutaml::Rdf::MappingRule` value object:
+
+* `name` — the local name in the namespace (e.g., `:prefLabel`)
+* `namespace:` — the `Lutaml::Rdf::Namespace` subclass (required, validated)
+* `to:` — the model attribute to read/write (required)
+* `lang_tagged:` (default: `false`) — if true, appends `@lang` suffix from the
+  value's `language_code` or `language` method
+
+Validation errors:
+
+* `namespace` must be a `Rdf::Namespace` subclass — raises `ArgumentError`
+* `to:` is required — raises `ArgumentError`
+
+== Serialization
+
+[source,ruby]
+----
+concept = Concept.new(name: "test", description: "A description", code: "2119")
+turtle = concept.to_turtle
+----
+
+Produces:
+
+[source,turtle]
+----
+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+
+<http://example.org/concept/2119> a skos:Concept;
+  skos:definition "A description";
+  skos:notation "2119";
+  skos:prefLabel "test" .
+----
+
+The output uses the `RDF::Turtle::Writer` from the `rdf-turtle` gem, which
+automatically compacts URIs using declared prefixes and uses native Turtle
+syntax for typed literals.
+
+=== Typed values
+
+Integer and boolean attributes are serialized using native Turtle literal
+syntax:
+
+* Integers → `42` (not `"42"^^xsd:integer`)
+* Booleans → `true` / `false` (not `"true"^^xsd:boolean`)
+
+=== Collection attributes
+
+When an attribute is defined with `collection: true`, each value produces a
+separate triple with the same predicate. The writer may use comma-separated
+object syntax:
+
+[source,turtle]
+----
+<http://example.org/1> skos:prefLabel "en", "fr" .
+----
+
+== Special Characters
+
+String values containing quotes, newlines, tabs, or backslashes are
+automatically escaped. The `RDF::Turtle::Writer` uses triple-quoted strings
+(`"""..."""`) for multi-line literals.
+
+== Nil Values
+
+Predicates for attributes with `nil` values are omitted from the output. If
+all predicates produce no data, the result is an empty string.
+
+== Deserialization
+
+[source,ruby]
+----
+concept = Concept.from_turtle(turtle_string)
+puts concept.code         # => "2119"
+puts concept.description  # => "A description"
+----
+
+The `from_turtle` method:
+
+. Parses the Turtle string into an `RDF::Graph` via `RDF::Turtle::Reader`
+. Finds subjects by `rdf:type` matching the declared type
+. Maps predicates back to model attributes using the declared predicate rules
+. Converts RDF typed literals back to Ruby types (integers, booleans, etc.)
+
+Language-tagged literals are extracted without the language tag.
+
+== Round-trip
+
+Model data round-trips through Turtle serialization:
+
+[source,ruby]
+----
+restored = Concept.from_turtle(concept.to_turtle)
+restored.code == concept.code          # => true
+restored.description == concept.description  # => true
+----
+
+== Error Handling
+
+* `Lutaml::Turtle::MissingSubjectError` — raised when serializing a model
+  without a `subject` block defined
+* `RDF::ReaderError` — raised by the RDF parser for malformed Turtle input
+* Both are wrapped in `Lutaml::Model::InvalidFormatError` by the format
+  pipeline
+
+== Architecture
+
+The Turtle format is composed of:
+
+* `Lutaml::Turtle::Adapter` — parses Turtle strings to `RDF::Graph` and
+  serializes graphs back to Turtle
+* `Lutaml::Turtle::Mapping` — empty subclass of `Rdf::Mapping`; inherits
+  `namespace`, `subject`, `type`, `predicate`, `members` DSL methods
+* `Lutaml::Turtle::Transform` — inherits from `Rdf::Transform`; bidirectional
+  transform between model instances and RDF graphs via `model_to_data` /
+  `data_to_model`
+
+== 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:
+
+[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
+----
+
+The `rdf` block also supports `members` for graph-level serialization, where a
+container model emits all member resources as separate subjects in the same
+Turtle document.
+
+See link:../_guides/rdf-serialization.adoc[Unified RDF Serialization] for the
+complete guide.

data/docs/_migrations/0-8-0-namespace-restructuring.adoc

@@ -873,6 +873,96 @@ xml do
 end
 ----
 
+== Custom XML Serialization Methods
+
+Custom XML methods declared via `with: { from: :foo_from_xml, to: :foo_to_xml }` continue to work in v0.8.0, but the runtime objects passed to them have changed. This section covers the API differences and the migration steps needed.
+
+=== `doc` is now a `CustomMethodWrapper`
+
+In v0.7.x the third argument of `def foo_to_xml(model, parent, doc)` was the underlying adapter document (Nokogiri-, Ox-, Oga-, REXML-backed). In v0.8.0 it is a `Lutaml::Xml::CustomMethodWrapper`, and `parent` is a `Lutaml::Xml::DataModel::XmlElement` rather than an adapter element. The wrapper exposes the same `create_element` / `add_text` / `add_attribute` / `add_element` surface, so straight-line code that uses only those methods keeps working.
+
+=== `add_element(parent, x)` raises `TypeError` for foreign element types
+
+`doc.add_element(parent, x)` accepts two shapes for `x`:
+
+* A `String`, parsed as an XML fragment via Moxml and grafted in as `DataModel::XmlElement` children. This is the path most existing custom methods rely on (e.g. passing the result of `instance.to_xml`).
+* A `Lutaml::Xml::DataModel::XmlElement`, added directly as a child.
+
+Anything else — most commonly a `Nokogiri::XML::Element` left over from a v0.7-style custom method that built fragments with `Nokogiri::XML::Builder` — now raises a `TypeError` with a message like:
+
+  add_element expects a String or XmlElement, got Nokogiri::XML::Element.
+  Call .to_xml on the element first.
+
+==== Fix
+
+Serialize the foreign element to a string before handing it to the wrapper:
+
+[source,ruby]
+----
+# v0.7-era pattern (works against Nokogiri-backed adapter doc, raises in 0.8)
+b.parent.elements.first.elements.each { |x| doc.add_element(parent, x) }
+
+# v0.8 fix — pass the string fragment, takes the Moxml path
+b.parent.elements.first.elements.each { |x| doc.add_element(parent, x.to_xml) }
+----
+
+The same applies to single-element handoffs:
+
+[source,ruby]
+----
+# v0.7-era
+elem = b.parent.elements.first
+doc.add_element(parent, elem)
+
+# v0.8 fix
+elem = b.parent.elements.first.to_xml
+doc.add_element(parent, elem)
+----
+
+=== Sibling walks: `parent.elements` → `current_context.children`
+
+Custom methods that introspect the document under construction — for example, an idempotency guard that checks whether a sibling element has already been emitted — need to be translated. The v0.7 idiom
+
+[source,ruby]
+----
+def already_emitted?(doc)
+  doc.parent.elements.detect { |x| x.name == "foo" }
+end
+----
+
+becomes
+
+[source,ruby]
+----
+def already_emitted?(doc)
+  doc.current_context.children.detect { |x| x.name == "foo" }
+end
+----
+
+If you need to support both v0.7 and v0.8 from the same codebase, use a version constant rather than `respond_to?` checks:
+
+[source,ruby]
+----
+def already_emitted?(doc)
+  siblings = if defined?(Lutaml::VERSION) && Gem::Version.new(Lutaml::VERSION) >= Gem::Version.new("0.8")
+               doc.current_context.children
+             else
+               doc.parent.elements
+             end
+  siblings.detect { |x| x.name == "foo" }
+end
+----
+
+=== Migration checklist for custom methods
+
+Audit each `with: { to: :*_to_xml }` method for the following patterns:
+
+. Does it call `Nokogiri::XML::Builder.new`, `Ox.dump`, or any other adapter-specific builder, then pass the resulting elements to `doc.add_element`? → Convert each element to a string via `.to_xml` (or equivalent) before passing.
+. Does it walk `doc.parent.elements` / `doc.parent.children`? → Translate to `doc.current_context.children`.
+. Does it cast `doc` to a specific adapter type, or call adapter-specific methods on it? → Replace with the wrapper API (`create_element`, `add_text`, `add_attribute`, `add_element`).
+
+Test by round-tripping a representative fixture through `Model.from_xml(file).to_xml` and asserting equivalence. Foreign types will now raise `TypeError` rather than being silently dropped.
+
 == Testing Your Migration
 
 After updating, run your test suite:

data/docs/_pages/serialization_adapters.adoc

@@ -25,6 +25,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
@@ -309,6 +311,35 @@ 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 the built-in JSON serialization with
+JSON-LD-specific constructs: `@context`, `@type`, and `@id`.
+
+The adapter uses the standard Ruby `JSON` library internally — no additional gem
+is required beyond `lutaml-model`.
+
+See the link:../guides/jsonld-serialization[JSON-LD Serialization guide] for
+mapping DSL details 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 with its own mapping DSL.
+
+Requires the `rdf-turtle` gem:
+
+[source,ruby]
+----
+gem "rdf-turtle", "~> 3.3"
+----
+
+See the link:../guides/turtle-serialization[Turtle Serialization guide] for
+mapping DSL details and usage examples.
+
+
 === Error handling
 
 When parsing invalid serialization format data, an `InvalidFormatError` is

data/docs/_references/index.adoc

@@ -39,6 +39,7 @@ Deep dives into specific features:
 
 * link:../format-independent-features[Format-Independent Features] - Cross-format mechanisms
 * link:../parent-root-context[Parent and Root Context] - Model hierarchy navigation
+* link:../rdf-namespaces[RDF Namespaces] - Namespace, NamespaceSet, Iri, Literal
 
 == See also
 

data/docs/_references/rdf-namespaces.adoc

@@ -0,0 +1,243 @@
+---
+title: RDF Namespaces
+nav_order: 12
+---
+
+= RDF Namespaces
+
+Lutaml::Model provides a comprehensive RDF infrastructure with `Namespace`,
+`NamespaceSet`, `Iri`, and `Literal` classes. These are shared by the JSON-LD
+and Turtle format adapters.
+
+== Namespace
+
+`Lutaml::Rdf::Namespace` is the abstract base class for RDF namespace
+vocabularies. Subclasses define `uri` and `prefix` at the class level:
+
+[source,ruby]
+----
+ns = Class.new(Lutaml::Rdf::Namespace)
+ns.uri "http://example.org/ns/"
+ns.prefix "ex"
+
+ns["someName"]       # => "http://example.org/ns/someName"
+ns.prefixed("Name")  # => "ex:Name"
+----
+
+=== Immutability
+
+Once set, `uri` and `prefix` are frozen and cannot be changed:
+
+[source,ruby]
+----
+ns = Class.new(Lutaml::Rdf::Namespace)
+ns.uri "http://example.org/ns/"
+ns.uri "http://other.org/"  # => raises FrozenError
+----
+
+Each subclass has independent state — setting `uri` on one does not affect
+another.
+
+=== Equality
+
+Namespace classes implement equality based on `uri` and `prefix`:
+
+[source,ruby]
+----
+ns1 = Class.new(Lutaml::Rdf::Namespace)
+ns1.uri "http://example.org/"
+ns1.prefix "ex"
+
+ns2 = Class.new(Lutaml::Rdf::Namespace)
+ns2.uri "http://example.org/"
+ns2.prefix "ex"
+
+ns1 == ns2  # => true
+----
+
+=== Compact IRI resolution
+
+[source,ruby]
+----
+Lutaml::Rdf::Namespace.resolve_compact_iri("skos:Concept", [SkosNamespace])
+# => "http://www.w3.org/2004/02/skos/core#Concept"
+
+Lutaml::Rdf::Namespace.resolve_compact_iri("plain_name", [SkosNamespace])
+# => "plain_name" (returned as-is when no colon present)
+----
+
+== NamespaceSet
+
+`Lutaml::Rdf::NamespaceSet` is an ordered, enumerable collection of namespace
+classes with O(1) prefix lookup:
+
+[source,ruby]
+----
+set = Lutaml::Rdf::NamespaceSet.new(
+  Lutaml::Rdf::Namespaces::SkosNamespace,
+  Lutaml::Rdf::Namespaces::DctermsNamespace
+)
+
+set["skos"]           # => SkosNamespace (O(1) lookup)
+set.size              # => 2
+set.resolve_compact_iri("skos:Concept")
+# => "http://www.w3.org/2004/02/skos/core#Concept"
+set.compact("http://www.w3.org/2004/02/skos/core#Concept")
+# => "skos:Concept"
+set.to_hash
+# => { "skos" => "http://www.w3.org/2004/02/skos/core#",
+#      "dcterms" => "http://purl.org/dc/terms/" }
+----
+
+=== Collision detection
+
+Adding two different namespace classes with the same prefix raises an error:
+
+[source,ruby]
+----
+set = Lutaml::Rdf::NamespaceSet.new(SkosNamespace)
+ns = Class.new(Lutaml::Rdf::Namespace)
+ns.uri "http://other.org/"
+ns.prefix "skos"
+set.add(ns)  # => raises ArgumentError: Prefix 'skos' conflicts
+----
+
+Adding the same class twice is allowed (idempotent).
+
+== Iri
+
+`Lutaml::Rdf::Iri` is an immutable value object for IRIs:
+
+[source,ruby]
+----
+iri = Lutaml::Rdf::Iri.new("http://example.org/concept/1")
+iri.to_s   # => "http://example.org/concept/1"
+iri.value  # => "http://example.org/concept/1" (frozen)
+
+# Expand compact → full
+set = Lutaml::Rdf::NamespaceSet.new(SkosNamespace)
+compact_iri = Lutaml::Rdf::Iri.new("skos:Concept")
+compact_iri.expand(set)  # => Iri("http://www.w3.org/2004/02/skos/core#Concept")
+
+# Compact full → compact
+full_iri = Lutaml::Rdf::Iri.new("http://www.w3.org/2004/02/skos/core#Concept")
+full_iri.compact(set)  # => "skos:Concept"
+----
+
+Implements `Comparable` for sorting.
+
+== Literal
+
+`Lutaml::Rdf::Literal` is a value object for RDF literals with optional
+datatype and language tag:
+
+[source,ruby]
+----
+# Plain literal
+lit = Lutaml::Rdf::Literal.new("hello")
+lit.to_turtle          # => '"hello"'
+lit.to_jsonld_term     # => "hello"
+
+# Language-tagged literal
+lit = Lutaml::Rdf::Literal.new("hello", language: "en")
+lit.to_turtle          # => '"hello"@en'
+lit.to_jsonld_term     # => { "@value" => "hello", "@language" => "en" }
+
+# Typed literal
+lit = Lutaml::Rdf::Literal.new("42", datatype: "http://www.w3.org/2001/XMLSchema#integer")
+lit.to_turtle          # => '"42"^^<http://www.w3.org/2001/XMLSchema#integer>'
+lit.to_jsonld_term     # => { "@value" => "42", "@type" => "xsd:integer" }
+----
+
+=== Special character escaping
+
+Quotes, newlines, tabs, and backslashes are automatically escaped in Turtle
+and JSON-LD output.
+
+== Standard W3C Namespaces
+
+Pre-defined namespace classes are in `Lutaml::Rdf::Namespaces`:
+
+[cols="1,1,1"]
+|===
+| Class | Prefix | URI
+
+| `SkosNamespace` | `skos` | `http://www.w3.org/2004/02/skos/core#`
+| `DctermsNamespace` | `dcterms` | `http://purl.org/dc/terms/`
+| `RdfSyntaxNamespace` | `rdf` | `http://www.w3.org/1999/02/22-rdf-syntax-ns#`
+| `RdfsNamespace` | `rdfs` | `http://www.w3.org/2000/01/rdf-schema#`
+| `OwlNamespace` | `owl` | `http://www.w3.org/2002/07/owl#`
+| `XsdNamespace` | `xsd` | `http://www.w3.org/2001/XMLSchema#`
+|===
+
+NOTE: `RdfNamespace` is a backward-compatible alias for `RdfSyntaxNamespace`.
+
+== Custom Namespaces
+
+Define your own by subclassing:
+
+[source,ruby]
+----
+class MyNamespace < Lutaml::Rdf::Namespace
+  uri "http://example.org/vocab/"
+  prefix "my"
+end
+
+MyNamespace["term"]  # => "http://example.org/vocab/term"
+----
+
+== Error hierarchy
+
+[cols="1,1"]
+|===
+| Class | Description
+
+| `Lutaml::Rdf::Error` | Base error for all RDF errors
+| `Lutaml::Turtle::MissingSubjectError` | Raised when Turtle mapping has no `subject` block
+|===
+
+== Unified RDF Mapping
+
+`Lutaml::Rdf::Mapping` is the unified mapping base class shared by both Turtle
+and JSON-LD format adapters. It provides the `rdf` DSL for defining
+predicate-based mappings once and using them for both output formats.
+
+See link:../_guides/rdf-serialization.adoc[Unified RDF Serialization] for the
+complete guide.
+
+=== MappingRule
+
+`Lutaml::Rdf::MappingRule` is a value object for predicate-to-attribute
+mappings:
+
+[source,ruby]
+----
+# Created by the `predicate` DSL method
+predicate :prefLabel, namespace: SkosNamespace, to: :name, lang_tagged: true
+----
+
+Each rule stores: `predicate_name`, `namespace`, `to` (attribute symbol), and
+`lang_tagged` flag.
+
+=== MemberRule
+
+`Lutaml::Rdf::MemberRule` is a value object for the `members` declaration in
+graph-level RDF mapping:
+
+[source,ruby]
+----
+# In a container model's rdf block
+members :concepts
+----
+
+Stores the attribute name referencing the collection of member models.
+
+=== Transform
+
+`Lutaml::Rdf::Transform` is the base transform class for RDF serialization,
+shared by both `Turtle::Transform` and `JsonLd::Transform`. It provides:
+
+* `resolve_subject_uri(mapping, instance)` — evaluates the subject block
+* `resolve_type_uri(mapping)` — resolves compact IRI to full URI
+* `resolve_type_compact(mapping)` — returns the compact IRI form
+* `extract_language(value)` — extracts language code from `LanguageTagged` values

data/docs/index.adoc

@@ -11,13 +11,14 @@ image:https://img.shields.io/github/license/lutaml/lutaml-model.svg[License]
 image:https://github.com/lutaml/lutaml-model/actions/workflows/rake.yml/badge.svg["Build", link="https://github.com/lutaml/lutaml-model/actions/workflows/rake.yml"]
 image:https://github.com/lutaml/lutaml-model/actions/workflows/dependent-tests.yml/badge.svg["Dependent tests", link="https://github.com/lutaml/lutaml-model/actions/workflows/dependent-tests.yml"]
 
-Lutaml::Model is a Ruby library for creating information models with attributes and types, providing flexible and comprehensive mechanisms for serializing to and from multiple formats including XML, JSON, YAML, TOML, and Hash.
+Lutaml::Model is a Ruby library for creating information models with attributes and types, providing flexible and comprehensive mechanisms for serializing to and from multiple formats including XML, JSON, YAML, TOML, JSON-LD, Turtle, and Hash.
 
 == Key features
 
 * **Model-driven design** - Define models with attributes and types
-* **Multi-format serialization** - XML, JSON, YAML, TOML, Hash, YAML Stream
+* **Multi-format serialization** - XML, JSON, YAML, TOML, JSON-LD, Turtle, Hash, YAML Stream
 * **XML namespace support** - Full W3C namespace implementation
+* **Linked Data support** - RDF namespaces, JSON-LD, and Turtle serialization
 * **Validation** - Built-in validation with custom rules
 * **Schema generation** - Generate XSD, JSON Schema, YAML Schema
 * **Polymorphism** - Handle multiple types elegantly

data/lib/lutaml/jsonld/adapter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Lutaml
+  module JsonLd
+    class Adapter < Lutaml::KeyValue::Document
+      def self.parse(jsonld_string, _options = {})
+        JSON.parse(jsonld_string, create_additions: false)
+      end
+
+      def to_jsonld(*args)
+        options = args.first || {}
+        data = @attributes
+        if options[:pretty]
+          JSON.pretty_generate(data, *args)
+        else
+          JSON.generate(data, *args)
+        end
+      end
+    end
+  end
+end