lutaml-model 0.8.4 → 0.8.5

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

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

data/lib/lutaml/jsonld/transform.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Lutaml
+  module JsonLd
+    class Transform < Lutaml::Rdf::Transform
+      def model_to_data(instance, _format, options = {})
+        mapping = extract_mapping(options)
+        return {} unless mapping
+
+        if mapping.rdf_members.any?
+          build_graph_document(mapping, instance)
+        else
+          build_resource_object(mapping, instance)
+        end
+      end
+
+      def data_to_model(data, _format, options = {})
+        mapping = extract_mapping(options)
+        return model_class.new unless mapping
+
+        hash = data.is_a?(String) ? JSON.parse(data) : data
+
+        if hash.key?("@graph") && hash["@graph"].is_a?(Array) && !hash["@graph"].empty?
+          graph_data = hash["@graph"]
+          first = graph_data.first
+          hash = first.is_a?(Hash) ? first : {}
+        end
+
+        hash = strip_jsonld_keywords(hash)
+
+        attrs = {}
+        mapping.rdf_predicates.each do |rule|
+          value = hash[rule.predicate_name]
+          next if value.nil?
+
+          attrs[rule.to] = if rule.lang_tagged && value.is_a?(Hash)
+                             flatten_language_map(value)
+                           else
+                             value
+                           end
+        end
+
+        build_instance(attrs, options)
+      end
+
+      private
+
+      def extract_mapping(options)
+        options[:mappings] || mappings_for(:jsonld, lutaml_register)
+      end
+
+      def build_graph_document(mapping, instance)
+        context = build_merged_context(mapping, instance)
+        graph = []
+
+        if mapping.rdf_subject
+          resource = build_resource_data(mapping, instance)
+          graph << resource unless resource.empty?
+        end
+
+        mapping.rdf_members.each do |member_rule|
+          collection = Array(instance.public_send(member_rule.attr_name))
+          collection.each do |member|
+            member_mapping = member.class.mappings[:jsonld]
+            next unless member_mapping
+
+            resource = build_resource_data(member_mapping, member)
+            graph << resource unless resource.empty?
+          end
+        end
+
+        { "@context" => context, "@graph" => graph }
+      end
+
+      def build_merged_context(mapping, instance)
+        context_hash = build_context_from_mapping(mapping).to_hash
+
+        mapping.rdf_members.each do |member_rule|
+          collection = Array(instance.public_send(member_rule.attr_name))
+          next if collection.empty?
+
+          member_mapping = collection.first.class.mappings[:jsonld]
+          next unless member_mapping
+
+          context_hash.merge!(build_context_from_mapping(member_mapping).to_hash)
+        end
+
+        context_hash
+      end
+
+      def build_context_from_mapping(mapping)
+        context = Context.new
+        mapping.namespace_set.each { |ns| context.prefix(ns) }
+        mapping.rdf_predicates.each do |pred|
+          if pred.lang_tagged
+            context.term(pred.predicate_name,
+                         id: pred.uri,
+                         container: :language)
+          else
+            context.term(pred.predicate_name, id: pred.uri)
+          end
+        end
+        context
+      end
+
+      def build_resource_object(mapping, instance)
+        context = build_context_from_mapping(mapping).to_hash
+        data = build_resource_data(mapping, instance)
+        { "@context" => context }.merge(data)
+      end
+
+      def build_resource_data(mapping, instance)
+        result = {}
+
+        if mapping.rdf_type
+          result["@type"] = resolve_type_compact(mapping)
+        end
+
+        if mapping.rdf_subject
+          result["@id"] = resolve_subject_uri(mapping, instance)
+        end
+
+        mapping.rdf_predicates.each do |rule|
+          value = instance.public_send(rule.to)
+          next if value.nil?
+          next if value.is_a?(String) && value.empty?
+
+          result[rule.predicate_name] = if rule.lang_tagged
+                                          build_language_map(value)
+                                        else
+                                          serialize_rdf_value(value)
+                                        end
+        end
+
+        result
+      end
+
+      def build_language_map(values)
+        case values
+        when Array
+          map = {}
+          values.each do |v|
+            lang = extract_language(v)
+            map[lang] = v.to_s if lang
+          end
+          map.empty? ? nil : map
+        else
+          lang = extract_language(values)
+          lang ? { lang => values.to_s } : values.to_s
+        end
+      end
+
+      def flatten_language_map(lang_map)
+        lang_map.values
+      end
+
+      def serialize_rdf_value(value)
+        case value
+        when Array then value.map { |v| serialize_rdf_value(v) }
+        when Integer, Float, TrueClass, FalseClass then value
+        else value.to_s
+        end
+      end
+
+      def strip_jsonld_keywords(data)
+        return data unless data.is_a?(Hash)
+
+        data.reject { |key, _| key.start_with?("@") }
+      end
+    end
+  end
+end

data/lib/lutaml/jsonld.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "model"
+require_relative "rdf"
+
+module Lutaml
+  module JsonLd
+    autoload :Context, "#{__dir__}/jsonld/context"
+    autoload :TermDefinition, "#{__dir__}/jsonld/term_definition"
+    autoload :Transform, "#{__dir__}/jsonld/transform"
+    autoload :Adapter, "#{__dir__}/jsonld/adapter"
+  end
+end
+
+Lutaml::Model::FormatRegistry.register(
+  :jsonld,
+  mapping_class: Lutaml::Rdf::Mapping,
+  adapter_class: Lutaml::JsonLd::Adapter,
+  transformer: Lutaml::JsonLd::Transform,
+  key_value: false,
+  rdf: true,
+  error_types: ["JSON::ParserError"],
+)

data/lib/lutaml/model/format_registry.rb

@@ -23,7 +23,7 @@ module Lutaml
         # @param adapter_options [Hash, nil] { available: [...], default: :name }
         def register(format, mapping_class:, adapter_class:, transformer:,
                      adapter_loader: nil, castable_type: nil, key_value: nil,
-                     error_types: nil, adapter_options: nil)
+                     rdf: nil, error_types: nil, adapter_options: nil)
           validate_registration!(format, mapping_class, transformer)
 
           registered_formats[format] = {
@@ -33,6 +33,7 @@ module Lutaml
             adapter_loader: adapter_loader,
             castable_type: castable_type,
             key_value: key_value,
+            rdf: rdf,
             error_types: error_types,
             adapter_options: adapter_options,
             registered_at: Time.now,
@@ -109,6 +110,14 @@ module Lutaml
           registered_formats.dig(format, :key_value) == true
         end
 
+        def rdf_formats
+          registered_formats.select { |_, info| info[:rdf] }.keys
+        end
+
+        def rdf?(format)
+          registered_formats.dig(format, :rdf) == true
+        end
+
         def error_types_for(format)
           registered_formats.dig(format, :error_types)
         end

data/lib/lutaml/model/serialize/format_conversion.rb

@@ -15,7 +15,12 @@ module Lutaml
         # @param block [Proc] The DSL block to evaluate
         def process_mapping(format, *_args, &)
           klass = ::Lutaml::Model::Config.mappings_class_for(format)
-          mappings[format] ||= klass.new
+          existing = mappings[format]
+          mappings[format] = if existing.nil? || !existing.is_a?(klass)
+                               klass.new
+                             else
+                               existing
+                             end
           mappings[format].instance_eval(&)
 
           if mappings[format].respond_to?(:finalize)
@@ -273,6 +278,17 @@ module Lutaml
           end
         end
 
+        # Define RDF mappings for multiple formats (Turtle, JSON-LD, etc.).
+        # Discovers RDF formats dynamically from FormatRegistry.
+        #
+        # @param block [Proc] The DSL block
+        def rdf(&block)
+          Lutaml::Model::FormatRegistry.rdf_formats.each do |format|
+            mappings[format] = Lutaml::Rdf::Mapping.new
+            mappings[format].instance_eval(&block)
+          end
+        end
+
         # Get resolved mapping for a format
         #
         # Delegates to TransformationRegistry for centralized caching

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.4"
+    VERSION = "0.8.5"
   end
 end

data/lib/lutaml/model.rb

@@ -10,6 +10,8 @@ module Lutaml
   autoload :Jsonl, "#{__dir__}/jsonl"
   autoload :Yamls, "#{__dir__}/yamls"
   autoload :Xml, "#{__dir__}/xml"
+  autoload :JsonLd, "#{__dir__}/jsonld"
+  autoload :Turtle, "#{__dir__}/turtle"
 
   module Model
     # Autoloads for lazy loading - set up BEFORE any requires
@@ -241,6 +243,10 @@ require "#{__dir__}/jsonl"
 require "#{__dir__}/yamls"
 require "#{__dir__}/xml"
 
+# Optional formats: require "lutaml/jsonld" or "lutaml/turtle" to enable.
+# These are not eagerly loaded because they depend on optional gems
+# (e.g., rdf-turtle) that most users don't need.
+
 # Prepend builder interface into Serialize
 # Builder must be prepended AFTER XML so its initialize runs first
 # (Builder -> XML InstanceMethods -> Serialize)

data/lib/lutaml/rdf/error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Rdf
+    class Error < Lutaml::Model::Error; end
+  end
+end