JSON-LD Context Parser

A JSON-LD @context parser that will normalize these contexts so that they can easily be used in your application.

This parser has the following functionality:

• Fetch contexts by URLs.
• Normalize JSON contexts.
• Merge arrays of contexts.
• Create a default @base entry if a base IRI is provided.
• Create @id entries for all @reverse occurences.
• Expand prefixes and @vocab in string values, @id, @type and @reverse.
• Context validation according to the JSON-LD specification while parsing (can be disabled).
• Term expansion with the ContextParser.expandTerm helper function.
• IRI compacting with the ContextParser.compactIri helper function.

Example input (with base IRI set to http://example.org/base):

[
  {
    "@vocab": "http://vocab.org/",
    "npmd": "https://linkedsoftwaredependencies.org/bundles/npm/",
    "p": { "@id": "pred1", "@language": "nl" }
  },
  "http://example.org/simple.jsonld",
]

With http://example.org/simple.jsonld containing:

{
  "xsd": "http://www.w3.org/2001/XMLSchema#",
  "name": "http://xmlns.com/foaf/0.1/name"
}

Example output:

{
  "@base": "http://example.org/base",
  "@vocab": "http://vocab.org/",

  "npmd": "https://linkedsoftwaredependencies.org/bundles/npm/",
  "p": { "@id": "http://vocab.org/pred1", "@language": "nl" },

  "xsd": "http://www.w3.org/2001/XMLSchema#",
  "name": "http://xmlns.com/foaf/0.1/name"
},

Install

This package can be installed via npm.

$ npm install jsonld-context-parser

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

Usage

API

Create a new parser

const ContextParser = require('jsonld-context-parser').ContextParser;

const myParser = new ContextParser();

Optionally, you can pass an options object with a custom document loader:

const myParser = new ContextParser({ documentLoader: myDocumentLoader });

Parse a context.

Either parse a context by URL:

const myContext = await myParser.parse('http://json-ld.org/contexts/person.jsonld');

by an non-normalized context:

const myContext = await myParser.parse({ ... });

or by an array of mixed contexts or URLs:

const myContext = await myParser.parse([
  'http://json-ld.org/contexts/person.jsonld',
  { ... },
  'https://linkedsoftwaredependencies.org/contexts/components.jsonld'
]);

Expand a term

Based on a context, terms can be expanded in vocab or base-mode.

Note that you should run the context through ContextParser.parse() before calling this function!

Base expansion

Base expansion is done based on the @base context entry. This should typically be used for expanding terms in the subject or object position.

// Expands `person` based on the @base IRI. Will throw an error if the final IRI is invalid.
ContextParser.expandTerm('person', context);

// Expands if `foaf` is present in the context
ContextParser.expandTerm('foaf:name', context);

// Returns the URI as-is
ContextParser.expandTerm('http://xmlns.com/foaf/0.1/name', context);

Vocab expansion

Vocab expansion is done based on the @vocab context entry. This should typically be used for expanding terms in the predicate position.

// Expands `name` based on the @vocab IRI.
ContextParser.expandTerm('name', context, true);

// Expands if `foaf` is present in the context
ContextParser.expandTerm('foaf:name', context, true);

// Returns the URI as-is
ContextParser.expandTerm('http://xmlns.com/foaf/0.1/name', context, true);

(Use ContextParser.expandTermSingle if you only want to apply one expansion iteration)

Compact an IRI

Based on a context, IRIs can be compacted in vocab or base-mode.

Note that you should run the context through ContextParser.parse() before calling this function!

Base compacting

Base compacting is done based on the @base context entry. This should typically be used for compacting terms in the subject or object position.

// Compacts to `something` if @base is `http://base.org/`.
ContextParser.compactIri('http://base.org/something', context);

// Compacts to `prefix:name` if `"prefix": "http://prefix.org/"` is in the context
ContextParser.compactIri('http://prefix.org/name', context);

// Returns the URI as-is if it is not present in the context in any way
ContextParser.compactIri('http://xmlns.com/foaf/0.1/name', context);

Vocab compacting

Vocab compacting is done based on the @vocab context entry. This should typically be used for compacting terms in the predicate position.

// Compacts to `something` if @vocab is `http://vocab.org/`.
ContextParser.compactIri('http://vocab.org/something', context, true);

// Compacts to `prefix:name` if `"prefix": "http://prefix.org/"` is in the context
ContextParser.compactIri('http://prefix.org/name', context, true);

// Compacts to `term` if `"term": "http://term.org/"` is in the context
ContextParser.compactIri('http://term.org/', context, true);

// Returns the URI as-is if it is not present in the context in any way
ContextParser.compactIri('http://xmlns.com/foaf/0.1/name', context, true);

(Use ContextParser.compactIriSingle if you only want to apply one compaction iteration)

Command-line

A command-line tool is provided to quickly normalize any context by URL, file or string.

Usage:

$ jsonld-context-parse url http://json-ld.org/contexts/person.jsonld
$ jsonld-context-parse file path/to/context.jsonld
$ jsonld-context-parse arg '{ "xsd": "http://www.w3.org/2001/XMLSchema#" }'

License

This software is written by Ruben Taelman.

This code is released under the MIT license.