`json_ld`

The json_ld library provides predicates for parsing, generating, expanding, and compacting JSON-LD 1.1 (JSON-based Serialization for Linked Data) documents based on the W3C Recommendation found at:

https://www.w3.org/TR/json-ld11/

This library builds on top of the json library for JSON parsing and generation, and uses the same representation choices for JSON data. It includes parametric objects whose parameters allow selecting the representation for parsed JSON objects (curly or list), JSON text strings (atom, chars, or codes) and JSON pairs (dash, equal, or colon).

API documentation

Open the ../../apis/library_index.html#json_ld link in a web browser.

Loading

To load all entities in this library, load the loader.lgt file:

| ?- logtalk_load(json_ld(loader)).

Testing

To test this library predicates, load the tester.lgt file:

| ?- logtalk_load(json_ld(tester)).

Parsing

JSON-LD documents can be parsed from various sources using the parse/2 predicate. Since JSON-LD is a superset of JSON, any valid JSON-LD document is also valid JSON:

| ?- json_ld::parse(file('document.jsonld'), Term).

| ?- json_ld::parse(atom('{"@context": {"name": "http://schema.org/name"}, "name": "Manu Sporny"}'), Term).

Generating

JSON-LD documents can be generated from Logtalk terms using the generate/2 predicate:

| ?- json_ld::generate(atom(Atom), {'@context'-{name-'http://schema.org/name'}, name-'Manu Sporny'}).

Expansion

Expansion is the process of removing the context and representing all properties and types as full IRIs. This is useful for processing JSON-LD data in a context-independent way:

| ?- json_ld::parse(atom('{"@context": {"name": "http://schema.org/name"}, "name": "Manu Sporny"}'), Doc),
     json_ld::expand(Doc, Expanded).
Doc = {'@context'-{name-'http://schema.org/name'}, name-'Manu Sporny'},
Expanded = [{'http://schema.org/name'-[{'@value'-'Manu Sporny'}]}]
yes

Compaction

Compaction is the process of applying a context to shorten IRIs to terms or compact IRIs. This is the inverse of expansion:

| ?- json_ld::expand({'@context'-{name-'http://schema.org/name'}, name-'Manu Sporny'}, Expanded),
     json_ld::compact(Expanded, {'@context'-{name-'http://schema.org/name'}}, Compacted).

Flattening

Flattening collects all node objects from a document into a flat @graph array, with nested objects replaced by references. Blank node identifiers are generated for nodes that don’t have an @id:

| ?- json_ld::parse(atom('{"@context":{"knows":"http://xmlns.com/foaf/0.1/knows"},"@id":"http://example.org/john","knows":{"@id":"http://example.org/jane"}}'), Doc),
     json_ld::expand(Doc, Expanded),
     json_ld::flatten(Expanded, Flattened).

Supported Features

The library supports the following JSON-LD 1.1 features:

Context processing:

Inline context definitions (@context)
Vocabulary mapping (@vocab)
Base IRI (@base)
Default language (@language)
Base direction (@direction)
Compact IRIs (prefix:suffix notation)
Term definitions (simple and expanded)
Type coercion (@type in term definitions)
Context arrays (multiple contexts)

Node objects:

Node identifiers (@id)
Node types (@type)
Blank node identifiers (_:name)

Value objects:

Typed values (@value with @type)
Language-tagged strings (@value with @language)
Direction-tagged strings (@value with @direction)

Graph support:

Named graphs (@graph)
Default graph

Collections:

Ordered lists (@list)
Unordered sets (@set)

Other features:

Reverse properties (@reverse)
Included blocks (@included)
Index preservation (@index)
Flattening algorithm (flatten/2)

Not currently supported:

Remote context fetching (contexts referenced by URL)
Framing algorithm
@import context processing

Representation

JSON-LD documents are represented using the same term conventions as the json library. The JSON-LD keywords (@context, @id, @type, etc.) are represented as atoms in the parsed terms. For example:

JSON-LD	term (default)
{“@id”: “http://example.org/”}	{‘@id’-’http://example.org/’}
{“@type”: “Person”}	{‘@type’-‘Person’}
{“@value”: “hello”, “@language”: “en”}	{‘@value’-hello, ‘@language’-en}
{“@list”: [1, 2, 3]}	{‘@list’-[1, 2, 3]}
{“@graph”: […]}	{‘@graph’-[…]}

As with the json library, objects can be represented using curly terms (default) or list terms, and pairs can use dash, equal, or colon notation.

json_ld