README.md

Important

Please consider a donation to keep the project available and maintained as an open-source.

The common experience with open-source is that no one wants to pay for it, but they will happily use it for free.

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

• conformance to the specification
• secure, stable, fast, A+ code (covered by ~1800 tests)
• minimal external dependencies
  • only jakarta.json-api is required
• simple to use

Status

Extensions

• LD-CLI is a native command line utility for Ubuntu, Mac, Windows
• JSON-LD-star expansion and compaction built-in support (experimental)
• Universal RDF Dataset Normalization Algorithm - URDNA2015
• Iridium CBOR-LD a CBOR-based Processor for Linked Data
• LEXREX semantic vocabularies visual builder and manager

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 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();

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

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

Local JSON Document

Document document = JsonDocument.of(InputStream) or JsonDocument.of(Reader) ...

JsonLd.expand(document).get();

JsonLd.compact(document, contextDocument).get();
...

Processing Timeout [experimental]

A processor gets terminated eventually after a specified time. Please note the duration does not cover DocumentLoader processing time. You have to set-up a read timeout separately.

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

HTTP Document Loader Timeout

Configure and set a custom HTTP document loader instance.

// since 1.4.0 - set read timeout
static DocumentLoader LOADER = HttpLoader.defaultInstance().timeount(Duration.ofSeconds(30));
...
JsonLd.expand(...).loader(LOADER).get();

Document caching

Configure LRU-based cache for loading documents. The argument determines size of the LRU-cache.

// since 1.4.0
JsonLd.toRdf("https://example/document.jsonld").loader(new LRUDocumentCache(loader, capacity)).get();

You can share an instance of LRUDocumentCache among multiple calls to reuse cached documents.

// since 1.4.0
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 processing policy on undefined terms. Ignore by default.

// since 1.4.1
JsonLd.expand(...).undefinedTermsPolicy(Fail|Warn|Ignore).get();

Installation

Titanium

Maven

Java 11+

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

Gradle

Java 8+, Android API Level >=24

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

JSON-P Provider

Add JSON-P provider, if it is not on the classpath already.

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 test case
• document
  • write javadoc
  • write a tutorial
  • proofread an existing documentation
• promote
  • star, share, the project
  • write an article
• sponsor
  • your requests get top priority
  • you will get a badge

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]