JSON-LD Streaming Parser


A fast and lightweight _streaming_ and 100% _spec-compliant_ JSON-LD 1.1 parser,
with RDFJS representations of RDF terms, quads and triples.

The streaming nature allows triples to be emitted _as soon as possible_, and documents _larger than memory_ to be parsed.

Make sure to enable the streamingProfile flag when parsing a JSON-LD document with a streaming profile
to exploit the streaming capabilities of this parser, as this is disabled by default.

Installation

``bash
$ npm install jsonld-streaming-parser
`

or

`bash
$ yarn add jsonld-streaming-parser
`

This package also works out-of-the-box in browsers via tools such as webpack and browserify.

Require

`javascript
import {JsonLdParser} from "jsonld-streaming-parser";
`

_or_

`javascript
const JsonLdParser = require("jsonld-streaming-parser").JsonLdParser;
`




Usage

JsonLdParser is a Node Transform stream
that takes in chunks of JSON-LD data,
and outputs RDFJS-compliant quads.

It can be used to pipe streams to,
or you can write strings into the parser directly.

$3

`javascript
const myParser = new JsonLdParser();

fs.createReadStream('myfile.jsonld')
.pipe(myParser)
.on('data', console.log)
.on('error', console.error)
.on('end', () => console.log('All triples were parsed!'));
`

$3

`javascript
const myParser = new JsonLdParser();

myParser
.on('data', console.log)
.on('error', console.error)
.on('end', () => console.log('All triples were parsed!'));

myParser.write('{');
myParser.write("@context": "https://schema.org/",);
myParser.write("@type": "Recipe",);
myParser.write("name": "Grandma's Holiday Apple Pie",);
myParser.write("aggregateRating": {);
myParser.write("@type": "AggregateRating",);
myParser.write("ratingValue": "4");
myParser.write(}});
myParser.end();
`

$3

`javascript
import { Store } from 'n3';
import { JsonLdParser } from 'jsonld-streaming-parser';
import { promisifyEventEmitter } from 'event-emitter-promisify';

const store = new Store();
const parser = new JsonLdParser();
parser.write('{"@id": "http://example.org/jesse", "@type": "http://example.org/Thing"}');
parser.end();
await promisifyEventEmitter(store.import(parser));

// Logs all the quads in the store
console.log(...store);
`

$3

This parser implements the RDFJS Sink interface,
which makes it possible to alternatively parse streams using the import method.

`javascript
const myParser = new JsonLdParser();

const myTextStream = fs.createReadStream('myfile.jsonld');

myParser.import(myTextStream)
.on('data', console.log)
.on('error', console.error)
.on('end', () => console.log('All triples were parsed!'));
`

$3

Using a context event listener,
you can collect all detected contexts.

`javascript
const myParser = new JsonLdParser();

const myTextStream = fs.createReadStream('myfile.jsonld');

myParser.import(myTextStream)
.on('context', console.log)
.on('data', console.error)
.on('error', console.error)
.on('end', () => console.log('All triples were parsed!'));
`

$3

Usually, JSON-LD is published via the application/ld+json media type.
However, when a JSON-LD context is attached via a link header,
then it can also be published via application/json and +json extension types.

This library exposes the JsonLdParser.fromHttpResponse
function to abstract these cases,
so that you can call it for any HTTP response,
and it will return an appropriate parser
which may or may not contain a custom header-defined context:

`javascript
const myParser = JsonLdParser.fromHttpResponse(
'http://example.org/my-file.json', // For example: response.url
'application/json', // For example: headers.get('content-type')
new Headers({ 'Link': '; rel=\"http://www.w3.org/ns/json-ld#context\"' }), // Optional: WHATWG Headers
{}, // Optional: Any options you want to pass to the parser
);

// Parse anything with myParser like usual
const quads = myParser.import(response.body);
`

The Headers object must implement the Headers interface from the WHATWG Fetch API.

This function will automatically detect the http://www.w3.org/ns/json-ld#streaming profile and set the streamingProfile flag.

Configuration

Optionally, the following parameters can be set in the JsonLdParser constructor:

* dataFactory: A custom RDFJS DataFactory to construct terms and triples. _(Default: require('@rdfjs/data-model'))_
* context: An optional root context to use while parsing. This can by anything that is accepted by jsonld-context-parser, such as a URL, object or array. _(Default: {})_
* baseIRI: An initial default base IRI. _(Default: '')_
* streamingProfile: If this parser can assume that parsed documents follow the streaming JSON-LD profile. If true, and a non-streaming document is detected, an error may be thrown. If false, non-streaming documents will be handled by preemptively buffering entries, which will lose many of the streaming benefits of this parser. _(Default: true)_
* documentLoader A custom loader for fetching remote contexts. This can be set to anything that implements IDocumentLoader _(Default: FetchDocumentLoader)_
* ignoreMissingContextLinkHeader: If the lack of JSON-LD context link headers on raw JSON documents should NOT result in an error. If true, raw JSON documents can be considered first-class JSON-LD documents. _(Default: false)_
* produceGeneralizedRdf: If blank node predicates should be allowed, they will be ignored otherwise. _(Default: false)_
* processingMode: The maximum JSON-LD version that should be processable by this parser. _(Default: 1.1)_
* strictValues: By default, JSON-LD requires that all properties (or @id's) that are not URIs, are unknown keywords, and do not occur in the context should be silently dropped. When setting this value to true, an error will be thrown when such properties occur. This also applies to invalid values such as language tags. This is useful for debugging JSON-LD documents. _(Default: false)_
* allowSubjectList: If RDF lists can appear in the subject position. _(Default: false)_
* validateValueIndexes: If @index inside array nodes should be validated. I.e., nodes inside the same array with the same @id, should have equal @index values. This is not applicable to this parser as we don't do explicit flattening, but it is required to be spec-compliant. _(Default: false)_
* defaultGraph: The default graph for constructing quads. _(Default: defaultGraph())_
* rdfDirection: The mode under which @direction should be handled. If undefined, @direction is considered a regular RDF 1.2 literal with a base direction. Alternatively, it can be set to either 'i18n-datatype', 'compound-literal', or 'disabled' _(Default: undefined)_
* normalizeLanguageTags: Whether or not language tags should be normalized to lowercase. _(Default: false for JSON-LD 1.1 (and higher), true for JSON-LD 1.0)_
* streamingProfileAllowOutOfOrderPlainType: When the streaming profile flag is enabled, @type entries MUST come before other properties since they may defined a type-scoped context. However, when this flag is enabled, @type entries that do NOT define a type-scoped context may appear anywhere just like a regular property.. _(Default: false)_
* skipContextValidation: If JSON-LD context validation should be skipped. This is useful when parsing large contexts that are known to be valid. _(Default: false)_
* rdfstar: If embedded nodes and annotated objects should be parsed according to the JSON-LD star specification. _(Default: true)_
* rdfstarReverseInEmbedded: If embedded nodes in JSON-LD star can have reverse properties. _(Default: false)_
* wellKnownMediaTypes: an array of media types that can also be parsed as JSON-LD. _(Default: ['application/activity+json'])_

`javascript
new JsonLdParser({
dataFactory: require('@rdfjs/data-model'),
context: 'https://schema.org/',
baseIRI: 'http://example.org/',
streamingProfile: true,
documentLoader: new FetchDocumentLoader(),
ignoreMissingContextLinkHeader: false,
produceGeneralizedRdf: false,
processingMode: '1.0',
errorOnInvalidIris: false,
allowSubjectList: false,
validateValueIndexes: false,
defaultGraph: namedNode('http://example.org/graph'),
rdfDirection: undefined,
normalizeLanguageTags: true,
rdfstar: true,
});
`

How it works

This parser does _not_ follow the recommended procedure for transforming JSON-LD to RDF,
because this does not allow stream-based handling of JSON.
Instead, this tool introduces an alternative _streaming_ algorithm that achieves spec-compliant JSON-LD parsing.

This parser builds on top of the jsonparse library,
which is a sax-based streaming JSON parser.
With this, several in-memory stacks are maintained.
These stacks are needed to accumulate the required information to emit triples/quads.
These stacks are deleted from the moment they are not needed anymore, to limit memory usage.

The algorithm makes a couple of (soft) assumptions regarding the structure of the JSON-LD document,
which is true for most typical JSON-LD documents.

* If there is a @context, it is the first entry of an object.
* If there is an @id, it comes right after @context, or is the first entry of an object.

If these assumptions are met, (almost) each object entry corresponds to a triple/quad that can be emitted.
For example, the following document allows a triple to be emitted after each object entry (except for first two lines):

`
{
"@context": "http://schema.org/",
"@id": "http://example.org/",
"@type": "Person", // --> a schema:Person.
"name": "Jane Doe", // --> schema:name "Jane Doe".
"jobTitle": "Professor", // --> schema:jobTitle "Professor".
"telephone": "(425) 123-4567", // --> schema:telephone "(425) 123-4567".
"url": "http://www.janedoe.com" // --> schema:url .
}
`

If not all of these assumptions are met, entries of an object are buffered until enough information becomes available, or if the object is closed.
For example, if no @id was present, values will be buffered until an @id is read, or if the object closed.

For example:

`
{
"@context": "http://schema.org/",
"@type": "Person",
"name": "Jane Doe",
"jobTitle": "Professor",
"@id": "http://example.org/", // --> a schema:Person.
// --> schema:name "Jane Doe".
// --> schema:jobTitle "Professor".
"telephone": "(425) 123-4567", // --> schema:telephone "(425) 123-4567".
"url": "http://www.janedoe.com" // --> schema:url .
}
`

As such, JSON-LD documents that meet these requirements will be parsed very efficiently.
Other documents will still be parsed correctly as well, with a slightly lower efficiency.

Streaming Profile

This parser adheres to the JSON-LD 1.1 specification,
the JSON-LD 1.1 Streaming specification,
and the JSON-LD star specification.

By default, this parser assumes that JSON-LD document
are not in the streaming document form.
This means that the parser may buffer large parts of the document before quads are produced,
to make sure that the document is interpreted correctly.

Since this buffering neglects the streaming benefits of this parser,
the streamingProfile flag should be enabled when a streaming JSON-LD document
is being parsed.

If non-streaming JSON-LD documents are encountered when the streamingProfile flag is enabled,
an error may be thrown.

Specification compliance

This parser implements the following JSON-LD specifications:

* JSON-LD 1.1 - Transform JSON-LD to RDF
* JSON-LD 1.1 - Error handling
* JSON-LD 1.1 - Streaming Transform JSON-LD to RDF
* JSON-LD star - Transform JSON-LD star to RDF
* JSON-LD star - Error handling

Performance

The following table shows some simple performance comparisons between JSON-LD Streaming Parser and jsonld.js.

These basic experiments show that even though streaming parsers are typically significantly slower than regular parsers,
_JSON-LD Streaming Parser still achieves similar performance as jsonld.js_ for most typical JSON-LD files.
However, for expanded JSON-LD documents, JSON-LD Streaming Parser is around 3~4 times slower.

| File | JSON-LD Streaming Parser | jsonld.js |
| ---------- | ---------------------------- | ------------- |
| toRdf-manifest.jsonld (999 triples) | 683.964ms (38MB) | 708.975ms (40MB) |
| sparql-init.json (69 triples) | 931.698ms (40MB) | 1088.607ms (47MB) |
| person.json (5 triples) | 309.419ms (30MB) | 313.138ms (41MB) |
| dbpedia-10000-expanded.json (10,000 triples) | 785.557ms (70MB) | 202.363ms (62MB) |

Tested files:

* toRdf-manifest.jsonld: The JSON-LD toRdf test manifest. A typical JSON-LD file with a single context.
* sparql-init.json: A Comunica configuration file. A JSON-LD file with a large number of complex, nested, and remote contexts.
* person.jsonld: A very small JSON-LD example from the JSON-LD playground.
* dbpedia-10000-expanded.json` First 10000 triples of DBpedia in expanded JSON-LD.

Code for measurements

License

This software is written by Ruben Taelman.

This code is released under the MIT license.