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 (covered by ~1800 tests)
• Minimal external dependencies
• Easy to use

Status

Extensions

• LD-CLI - A native command line utility for Ubuntu, Mac, and Windows
• JSON-LD-star - Expansion and compaction built-in support (experimental)
• 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 - A CBOR-based Processor for Linked Data
• RDF-URDNA - Universal RDF Dataset Normalization Algorithm 2015

Table of Contents

• Conformance
• Examples
• Installation
• Documentation
• Contributing
• Resources
• Commercial Support

Conformance

Feature	Tests	Pass	Status	Notes
Expansion	373	373	100%
Compaction	243	243	100%
Flattening	55	55	100%
JSON-LD to RDF	453	451	99.5%	te075 - @vocab as blank node identifier tli12 - List with bad @base
RDF to JSON-LD	51	51	100%
Framing	89	88	98.8%	t0059 - @embed: @last
Remote Document and Context Retrieval	18	17	94.4%	t0013 - HTML document

See EARL results from the JSON-LD 1.1 Test Suite for more details.

Examples

Titanium provides a high-level JsonLd API to interact with the processor.

Transformations

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

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

// Compaction
JsonLd.compact("https://example/expanded.jsonld", "https://example/context.jsonld")
      .compactToRelative(false)
      .get();

// Flattening
JsonLd.flatten("https://example/document.jsonld").get();

// JSON-LD to RDF 
JsonLd.toRdf("https://example/document.jsonld").get();
// or, since 1.6.0
JsonLd.toRdf("https://example/document.jsonld").provide(RdfConsumer); 

// Standard RDF Dataset Canonicalization with Titanium RDFC, since 1.6.0
var canonicalizer = new RdfCanon.create(...);
JsonLd.toRdf("https://example/document.jsonld").provide(canonicalizer);
canonicalizer.provide(RdfConsumer);
// or, with NQuadsWriter
canonicalizer.provide(new NQuadsWriter(...));

// RDF to JSON-LD
JsonLd.fromRdf("https://example/document.nq").get();

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

Local JSON Document

// Create a JSON document from InputStream or Reader
Document document = JsonDocument.of(InputStream) or JsonDocument.of(Reader) ...

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

// Compact the document with a context document
JsonLd.compact(document, contextDocument).get();
...

Processing Timeout [Experimental]

The processor will be terminated after a specified duration. Please note that the duration does not include the time taken by DocumentLoader for processing. You must set up a separate read timeout for document loading.

// Available since 1.4.0
JsonLd.expand(...).timeout(duration)...get();

HTTP Document Loader Timeout

You can configure a custom HTTP document loader instance with a set read timeout.

// Available since 1.4.0 - Set read timeout for HTTP document loader
static DocumentLoader LOADER = HttpLoader.defaultInstance().timeout(Duration.ofSeconds(30));
...
JsonLd.expand(...).loader(LOADER).get();

Document Caching

Configure an LRU-based cache for loading documents. The capacity argument specifies the size of the LRU cache.

// Available since 1.4.0 - Load documents with an LRU-based cache
JsonLd.toRdf("https://example/document.jsonld").loader(new LRUDocumentCache(loader, capacity)).get();

You can reuse an instance of LRUDocumentCache across multiple calls to benefit from cached documents.

// Available since 1.4.0 - Reuse LRU cache across multiple document loads
DocumentLoader cachedLoader = new LRUDocumentCache(loader, capacity);

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

Undefined Terms Processing Policy

Set a processing policy for undefined terms. The default policy is Ignore.

// Available since 1.4.1 - Define processing policy for undefined terms
JsonLd.expand(...).undefinedTermsPolicy(Fail|Warn|Ignore).get();

Installation

Titanium

Maven (Java 11+)

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

Gradle (Java 8+, Android API Level >= 24)

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

JSON-P Provider

Ensure that the JSON-P provider is added to the classpath if it is not already present.

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

Documentation

Contributing

All PR's welcome!

• Develop
  • Implement a new feature
  • Fix an existing issue
  • Improve an existing implementation
• Test
  • Report a bug
  • Implement a new test case
• Document
  • Write Javadoc comments
  • Write a tutorial or guide
  • Proofread existing documentation for clarity and accuracy
• Promote
  • Star, share, the project
  • Write an article or blog post about the project
• Sponsor
  • Sponsorship gives your requests top priority

Building

Fork and clone the project repository.

Java 11

> cd titanium-json-ld
> mvn clean package

Java 8

> cd titanium-json-ld
> mvn -f pom_jre8.xml clean 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 is available at [email protected]