lutaml-model 0.8.3 → 0.8.5

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/_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/_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/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

data/lib/lutaml/jsonld/context.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module JsonLd
+    class Context
+      attr_reader :prefixes, :terms
+
+      def initialize
+        @prefixes = {}
+        @terms = {}
+        @vocab = nil
+        @language = nil
+        @base = nil
+      end
+
+      def prefix(namespace_class)
+        @prefixes[namespace_class.prefix] = namespace_class.uri
+      end
+
+      def vocab(uri = nil)
+        @vocab = uri if uri
+        @vocab
+      end
+
+      def language(lang = nil)
+        @language = lang if lang
+        @language
+      end
+
+      def base(uri = nil)
+        @base = uri if uri
+        @base
+      end
+
+      def term(name, id: nil, type: nil, container: nil, language: nil,
+reverse: false)
+        @terms[name] = TermDefinition.new(
+          name: name,
+          id: id,
+          type: type,
+          container: container,
+          language: language,
+          reverse: reverse,
+        )
+      end
+
+      def to_hash
+        ctx = {}
+        ctx["@vocab"] = @vocab if @vocab
+        ctx["@language"] = @language if @language
+        ctx["@base"] = @base if @base
+        @prefixes.each { |pfx, uri| ctx[pfx] = uri }
+        @terms.each_value { |td| ctx.merge!(td.to_context_hash) }
+        ctx
+      end
+
+      def resolve(term_name)
+        if term_name.include?(":")
+          pfx, local = term_name.split(":", 2)
+          "#{@prefixes[pfx]}#{local}" if @prefixes.key?(pfx)
+        elsif @terms.key?(term_name)
+          @terms[term_name].id
+        elsif @vocab
+          "#{@vocab}#{term_name}"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/jsonld/term_definition.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module JsonLd
+    class TermDefinition
+      attr_reader :name, :id, :type, :container, :language, :reverse
+
+      def initialize(name:, id: nil, type: nil, container: nil, language: nil,
+reverse: false)
+        @name = name
+        @id = id
+        @type = type
+        @container = container
+        @language = language
+        @reverse = reverse
+      end
+
+      def to_context_hash
+        if simple_mapping?
+          { @name => @id }
+        else
+          defn = {}
+          defn["@id"] = @id if @id
+          defn["@type"] = @type if @type
+          defn["@container"] = "@#{@container}" if @container
+          defn["@language"] = @language if @language
+          defn["@reverse"] = @reverse if @reverse
+          { @name => defn }
+        end
+      end
+
+      private
+
+      def simple_mapping?
+        @id && @type.nil? && @container.nil? && @language.nil? && !@reverse
+      end
+    end
+  end
+end