Titanium JSON-LD 1.1 Processor & API

An implementation of the JSON-LD 1.1 (JSON-based Serialization for Linked Data) specification in Java, utilizing Jakarta JSON Processing.

🎯 Goals

• Full conformance to the specification
• Secure, stable, fast, high-quality code (~2900 tests)
• Minimal external dependencies
• Simple and easy-to-use

🚦 Status

🧩 Libraries & Tools

• LD-CLI - A native command line utility for Ubuntu, Mac, and Windows
• Titanium RDFC - W3C Standard RDF Dataset Canonicalization
• Titanium N-QUADS - W3C RDF 1.1 N-Quads
• Titanium JCS - RFC 8785 JSON Canonicalization Scheme (JCS)
• Iridium CBOR-LD - CBOR-based Processor for Linked Data

✅ Conformance

Feature	Tests	Pass	Pass Rate	Notes
Expansion	376	376	100%
Compaction	244	244	100%
Flattening	55	55	100%
JSON-LD to RDF	456	454	99.6%	te075 - @vocab as blank node identifier tli12 - List with bad @base
RDF to JSON-LD	52	52	100%
Framing	91	90	98.9%	t0059 - @embed: @last
Remote Document and Context Retrieval	18	17	94.4%	t0013 - HTML document

📄 See also: EARL Results from the JSON-LD 1.1 Test Suite

💡 Examples

Titanium provides a high-level JsonLd API for working with JSON-LD documents.

Transformations

Perform standard JSON-LD operations such as expansion, compaction, flattening, framing, and conversion from/to RDF. The JSON-LD document to process can be remote or local.

// Expansion from a remote JSON-LD document
JsonLd.expand("https://w3c.github.io/json-ld-api/tests/expand/0001-in.jsonld")
      .ordered()
      .get();

// Expansion from a local file with an external context
JsonLd.expand("file:/home/filip/document.json")    // HTTP(S) and File schemes supported
      .context("file:/home/filip/context.jsonld")  // external context
      .get();

// Compaction with a remote context
JsonLd.compact("https://example/expanded.jsonld", "https://example/context.jsonld")
      .compactToRelative(false)  // use absolute IRIs
      .get();

// Flattening a JSON-LD document
JsonLd.flatten("https://example/document.jsonld").get();

// Convert JSON-LD to RDF
JsonLd.toRdf("https://example/document.jsonld").provide(RdfConsumer); 

// RDF Dataset Canonicalization with Titanium RDFC
var canonicalizer = new RdfCanon.create(...);
JsonLd.toRdf("https://example/document.jsonld").provide(canonicalizer);
canonicalizer.provide(RdfConsumer);
// or with N-Quads output
canonicalizer.provide(new NQuadsWriter(...));

// Convert RDF to JSON-LD
var consumer = JsonLd.fromRdf();
consumer.quad(...);  // feed manually or via a reader
(new NquadsReader(...)).provide(consumer);

// Get the final JSON-LD result
consumer.toJsonLd();

// Framing a document
JsonLd.frame("https://example/document.jsonld", "https://example/frame.jsonld").get();

Local JSON Document

Load and process JSON-LD documents directly from an InputStream or Reader.

// Load JSON from InputStream or Reader
Document document = JsonDocument.of(inputStream);
Document context = JsonDocument.of(reader);

// Expand the local document
JsonLd.expand(document).get();

// Compact using a local context
JsonLd.compact(document, context).get();

Processing Timeout [Experimental]

Set a maximum processing duration for JSON-LD operations. The timeout does not include time spent loading external documents.

// Terminates processing after the specified duration (excluding DocumentLoader time)
JsonLd.expand(document)
      .timeout(Duration.ofSeconds(5))
      .get();

HTTP Document Loader Timeout

Customize the HTTP loader to apply a read timeout when fetching remote JSON-LD or context documents.

// Configure a custom HTTP loader with a 30-second read timeout
static DocumentLoader LOADER = HttpLoader.defaultInstance().timeout(Duration.ofSeconds(30));
...
JsonLd.expand(...).loader(LOADER).get();

Document Caching

Use an LRU-based cache to reuse previously loaded documents and reduce network calls. A cache instance can be shared across multiple operations.

// LRU cache for remote documents (capacity = 100)
JsonLd.expand("https://example.com/document.jsonld")
      .loader(new LRUDocumentCache(loader, 100))
      .get();

// Reuse cache across multiple documents
DocumentLoader cachedLoader = new LRUDocumentCache(loader, 100);

JsonLd.expand("https://example.com/document.jsonld").loader(cachedLoader).get();
JsonLd.expand("https://example.com/another-document.jsonld").loader(cachedLoader).get();

Undefined Terms Processing Policy

Define how the processor handles terms not defined in the context. Options include Fail, Warn, or Ignore (default).

// Define behavior for undefined terms: Fail, Warn, or Ignore (default)
JsonLd.expand(document)
      .undefinedTermsPolicy(Fail)  // or Warn | Ignore
      .get();

📘 Learn more: See the Javadoc API Reference for advanced configuration and usage options.

⚙️ Installation

Titanium

Maven (Java 11+)

<dependency>
    <groupId>com.apicatalog</groupId>
    <artifactId>titanium-json-ld</artifactId>
    <version>1.7.0</version>
</dependency>

Gradle (Java 8+, Android API Level ≥ 24)

implementation("com.apicatalog:titanium-json-ld-jre8:1.7.0")

Warning

The upcoming 2.x version is under active development and requires Java 17 or higher. 2.x milestone releases are provided for testing and feedback purposes only and should not be used in production.

Each milestone can introduce breaking changes.

JSON-P Provider

Titanium relies on a JSON-P (Jakarta JSON Processing) provider. Ensure that one is available on your classpath.

Maven

<dependency>
    <groupId>org.glassfish</groupId>
    <artifactId>jakarta.json</artifactId>
    <version>2.0.1</version>
</dependency>

Gradle

implementation("org.glassfish:jakarta.json:2.0.1")

🤝 Contributing

Contributions of all kinds are welcome — whether it’s code, documentation, testing, or community support! Please open a pull request or issue to get started.

💻 Develop

• Implement a new feature
• Fix an existing issue or bug
• Refactor or optimize existing code

🧪 Test

• Report bugs or unexpected behavior
• Add or improve unit/integration tests
• Verify milestone builds and provide feedback

📖 Document

• Write or improve Javadoc and inline comments
• Create or update tutorials and usage guides
• Proofread and improve clarity or accuracy in documentation

🌟 Promote

• Star ⭐ and share the project
• Write a blog post, article, or social media post about it
• Help answer questions or guide new contributors

💖 Sponsor

Your support helps sustain development.

🏗️ Building

Fork and clone the project repository.

Note

Version 2.0 is under active development! The new major version 2.0 requires Java 17 and is released in milestones before the final release.

Each milestone can introduce breaking changes and is intended only for testing.

> cd titanium-json-ld
> mvn package

📚 Resources

• JSON-LD 1.1
• JSON-LD 1.1 Processing Algorithms and API
• JSON-LD 1.1 Framing
• JSON-LD Best Practices
• JSON-LD-star
• JSON-LD Playground

💼 Commercial Support

Commercial support and consulting are available. For inquiries, please contact: [email protected]