https://github.com/filip26/titanium-json-ld
A JSON-LD 1.1 Processor & API
https://github.com/filip26/titanium-json-ld
java json json-ld json-ld-11 jsonld linked-data rdf semantic-web structured-data
Last synced: about 1 month ago
JSON representation
A JSON-LD 1.1 Processor & API
- Host: GitHub
- URL: https://github.com/filip26/titanium-json-ld
- Owner: filip26
- License: apache-2.0
- Created: 2020-05-12T22:10:07.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2025-03-28T13:26:23.000Z (about 1 month ago)
- Last Synced: 2025-03-31T20:05:26.591Z (about 1 month ago)
- Topics: java, json, json-ld, json-ld-11, jsonld, linked-data, rdf, semantic-web, structured-data
- Language: Java
- Homepage: https://apicatalog.com
- Size: 4.7 MB
- Stars: 143
- Watchers: 7
- Forks: 34
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-ccamel - filip26/titanium-json-ld - A JSON-LD 1.1 Processor & API (Java)
- awesome-java-rdf - titanium-json-ld
- awesome-java-rdf - titanium-json-ld
README
# Titanium JSON-LD 1.1 Processor & API
An implementation of the [JSON-LD 1.1](https://www.w3.org/TR/json-ld/) (JSON-based Serialization for Linked Data) specification in Java, utilizing [Jakarta JSON Processing](https://github.com/eclipse-ee4j/jsonp).
### Goals
- Full conformance to the specification
- Secure, stable, fast, high-quality code (covered by **~1800 tests**)
- Minimal external dependencies
- Easy to use
### Status
[](https://github.com/filip26/titanium-json-ld/actions/workflows/java11-build.yml)
[](https://github.com/filip26/titanium-json-ld/actions/workflows/java8-build.yml)
[](https://github.com/filip26/titanium-json-ld/actions/workflows/codeql.yml)
[](https://app.codacy.com/gh/filip26/titanium-json-ld/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[](https://app.codacy.com/gh/filip26/titanium-json-ld/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
[](https://search.maven.org/search?q=g:com.apicatalog%20AND%20a:titanium-json-ld)
[](https://opensource.org/licenses/Apache-2.0)
### Extensions
- [LD-CLI](https://github.com/filip26/ld-cli) - A native command line utility for Ubuntu, Mac, and Windows
- [JSON-LD-star](https://json-ld.github.io/json-ld-star) - Expansion and compaction built-in support (experimental)
- [Titanium RDFC](https://github.com/filip26/titanium-rdfc) - W3C Standard RDF Dataset Canonicalization
- [Titanium N-QUADS](https://github.com/filip26/titanium-rdf-n-quads) - W3C RDF 1.1 N-Quads
- [Titanium JCS](https://github.com/filip26/titanium-jcs) - RFC 8785 JSON Canonicalization Scheme (JCS)
- [Iridium CBOR-LD](https://github.com/filip26/iridium-cbor-ld) - A CBOR-based Processor for Linked Data
- [RDF-URDNA](https://github.com/simon-greatrix/rdf-urdna) - Universal RDF Dataset Normalization Algorithm 2015
## Table of Contents
- [Conformance](#conformance)
- [Examples](#examples)
- [Installation](#installation)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [Resources](#resources)
- [Commercial Support](#commercial-support)
## Conformance
| Feature | Tests | Pass | Status | Notes |
| --- | ---: | ---: | ---: | --- |
| [Expansion](https://www.w3.org/TR/json-ld/#expanded-document-form) | 373 | 373 | 100% | |
| [Compaction](https://www.w3.org/TR/json-ld/#compacted-document-form) | 243 | 243 | 100% | |
| [Flattening](https://www.w3.org/TR/json-ld/#flattened-document-form) | 55 | 55 | 100% | |
| [JSON-LD to RDF](https://www.w3.org/TR/json-ld/#relationship-to-rdf) | 453 | 451 | 99.5% |
- [te075 - @vocab as blank node identifier](https://w3c.github.io/json-ld-api/tests/toRdf-manifest#te075)
- [tli12 - List with bad @base](https://w3c.github.io/json-ld-api/tests/toRdf-manifest#tli12)
| [RDF to JSON-LD](https://www.w3.org/TR/json-ld/#relationship-to-rdf) | 51 | 51 | 100% | |
| [Framing](https://www.w3.org/TR/json-ld11-framing/#framing) | 89 | 88 | 98.8% |
- [t0059 - @embed: @last](https://w3c.github.io/json-ld-framing/tests/frame-manifest#t0059)
| [Remote Document and Context Retrieval](https://www.w3.org/TR/json-ld11-api/#remote-document-and-context-retrieval) | 18 | 17 | 94.4% |
- [t0013 - HTML document](https://w3c.github.io/json-ld-api/tests/remote-doc-manifest#t0013)
See [EARL results from the JSON-LD 1.1 Test Suite](https://w3c.github.io/json-ld-api/reports/#subj_Titanium_JSON_LD_Java) for more details.
## Examples
Titanium provides a high-level [JsonLd](https://javadoc.io/doc/com.apicatalog/titanium-json-ld/latest/com/apicatalog/jsonld/JsonLd.html) API to interact with the processor.
### Transformations
```javascript
// 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
```javascript
// 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.
```javascript
// 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.
```javascript
// 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.
```javascript
// 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.
```javascript
// 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`.
```javascript
// Available since 1.4.1 - Define processing policy for undefined terms
JsonLd.expand(...).undefinedTermsPolicy(Fail|Warn|Ignore).get();
```
## Installation
### Titanium
#### Maven (Java 11+)
```xml
com.apicatalog
titanium-json-ld
1.6.0
```
#### Gradle (Java 8+, Android API Level >= 24)
```gradle
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
```xml
org.glassfish
jakarta.json
2.0.1
```
#### Gradle
```gradle
implementation("org.glassfish:jakarta.json:2.0.1")
```
## Documentation
[](https://javadoc.io/doc/com.apicatalog/titanium-json-ld)
## 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
```bash
> cd titanium-json-ld
> mvn clean package
```
#### Java 8
```bash
> cd titanium-json-ld
> mvn -f pom_jre8.xml clean package
```
## Resources
- [JSON-LD 1.1](https://www.w3.org/TR/json-ld/)
- [JSON-LD 1.1 Processing Algorithms and API](https://www.w3.org/TR/json-ld-api/)
- [JSON-LD 1.1 Framing](https://www.w3.org/TR/json-ld-framing/)
- [JSON-LD Best Practices](https://w3c.github.io/json-ld-bp/)
- [JSON-LD-star](https://json-ld.github.io/json-ld-star/)
- [JSON-LD Playground](https://json-ld.org/playground/)
## Commercial Support
Commercial support is available at [email protected]