lutaml-model 0.8.4 → 0.8.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c512d678682ea756cb7eb7a3d439a7d511b763405936e598900f42f7f07aa705
-  data.tar.gz: e6623585797f809090619a9e6268e026773d962cac0f940ccae608627d8e714c
+  metadata.gz: 2bc036758cf2a4ac1420e14fc6be130730410ab183cd002ced260bdbf08793eb
+  data.tar.gz: 1dfc1b473558992eb1481a535d86c1688313951530762c9317af90413028032e
 SHA512:
-  metadata.gz: 81558e237a6a7f55c3defee45c8fa8a1d59bf75a875159708065ce8db44308fdaa17d3c727d6ff1074477391ec199008088221f54d5bbb7f2b3b4546ff4d25cf
-  data.tar.gz: 242730ac59628f328fe07409cc54d7798e75b40d29b6b47ad7382de37a033d9f907d0578d8ab950c45c9ff1b06cd67f6cb98e3e6215948149e63e8e4591be15d
+  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-06 04:21:39 UTC using RuboCop version 1.86.0.
+# 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,7 +11,7 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'lutaml-model.gemspec'
 
-# Offense count: 3232
+# Offense count: 3264
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
@@ -34,16 +34,10 @@ Lint/ConstantDefinitionInBlock:
 Lint/DuplicateBranch:
   Enabled: false
 
-# Offense count: 22
+# Offense count: 3
 Lint/DuplicateMethods:
   Exclude:
     - 'lib/lutaml/xml/mapping.rb'
-    - 'spec/lutaml/model/liquid_compatibility_spec.rb'
-    - 'spec/lutaml/xml/namespace_no_hoisting_spec.rb'
-    - 'spec/lutaml/xml/namespace_scope_declare_spec.rb'
-    - 'spec/lutaml/xml/namespace_scope_vcard_spec.rb'
-    - 'spec/lutaml/xml/prefix_control_spec.rb'
-    - 'spec/lutaml/xml/type_namespace_examples_spec.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
@@ -116,7 +110,7 @@ Lint/UselessConstantScoping:
     - 'lib/lutaml/xml/adapter/nokogiri_adapter.rb'
     - 'lib/lutaml/xml/mapping_rule.rb'
 
-# Offense count: 346
+# Offense count: 355
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
@@ -132,23 +126,23 @@ Metrics/BlockLength:
 Metrics/BlockNesting:
   Max: 6
 
-# Offense count: 309
+# Offense count: 315
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 562
+# Offense count: 575
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 514
 
-# Offense count: 86
+# Offense count: 88
 # Configuration parameters: CountKeywordArgs.
 Metrics/ParameterLists:
   Max: 24
   MaxOptionalParameters: 5
 
-# Offense count: 260
+# Offense count: 264
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
@@ -240,7 +234,7 @@ RSpec/BeforeAfterAll:
 RSpec/ContextWording:
   Enabled: false
 
-# Offense count: 88
+# Offense count: 92
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
@@ -251,7 +245,7 @@ RSpec/DescribeMethod:
     - 'spec/lutaml/xml/schema/xsd/schema_helper_methods_spec.rb'
     - 'spec/lutaml/xml/serializable_namespace_spec.rb'
 
-# Offense count: 1207
+# Offense count: 1234
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 68
@@ -326,7 +320,7 @@ RSpec/MultipleDescribes:
     - 'spec/lutaml/xml/namespace_resolution_strategy_spec.rb'
     - 'spec/lutaml/xml/xml_space_type_spec.rb'
 
-# Offense count: 1383
+# Offense count: 1442
 RSpec/MultipleExpectations:
   Max: 21
 
@@ -374,7 +368,7 @@ RSpec/RepeatedExampleGroupDescription:
   Exclude:
     - 'spec/lutaml/model/mixed_content_spec.rb'
 
-# Offense count: 35
+# Offense count: 40
 # Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata, InflectorPath, EnforcedInflector.
 # SupportedInflectors: default, active_support
 RSpec/SpecFilePathFormat:

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,6 +65,7 @@ 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>>)
 
@@ -5391,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]
@@ -5439,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
@@ -10100,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
 
@@ -15735,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
@@ -15977,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:

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
@@ -49,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