Titanium JSON-LD 1.1 Processor & API

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

✨ Features

• No vibe coding. No generated code. Just deliberate engineering
• Full conformance with the JSON-LD 1.1 specification
• Secure, stable, high-performance implementation with ~3000 tests
• Minimal external dependencies
• Simple, easy-to-use API
• Extensions (since v2.0):
  • JSON-LD-star expansion (experimental)
  • Processing policies: undefined terms, dropped values, time/space constraints
  • Generated TypeMap / TermMap (experimental)
  • Built-in loaders: HTTPS, file, classpath, scheme router, URI rewriter, LRUCache, in-memory
  • Generalized processing with tree-io (Jakarta JSON, Jackson, or anything else)

🎯 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")

JSON-P Provider

Titanium v1.x.x 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.

> 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: filip26@gmail.com