Home

Awesome

JSON-LD Context Parser

Build status Coverage Status npm version

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:

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, the following constructor options can be passed:

const myParser = new ContextParser({
  documentLoader: new FetchDocumentLoader(),
  skipValidation: true,
  expandContentTypeToBase: true,
});

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'
]);

Optionally, the following parsing options can be passed:

const myContext = await myParser.parse({ ... }, {
  baseIRI: 'http://example.org/',
  parentContext: {},
  external: true,
  processingMode: 1.0,
  normalizeLanguageTags: true,
  ignoreProtection: true,
  minimalProcessing: true,
  ignoreRemoteScopedContexts: true,
  remoteContexts: {
    'http://example.org/context.json': true,
  }
});

Expand a term

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

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.
myContext.expandTerm('person');

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

// Returns the URI as-is
myContext.expandTerm('http://xmlns.com/foaf/0.1/name');
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.
myContext.expandTerm('name', true);

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

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

Optionally, the following options can be passed for expansion:

myContext.expandTerm('person', false, {
  allowPrefixNonGenDelims: false,
  allowPrefixForcing: false,
  allowVocabRelativeToBase: true,
});

The defaultExpandOptions variable that is exported from this package contains the default expansion options hash.

Compact an IRI

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

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/`.
myContext.compactIri('http://base.org/something');

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

// Returns the URI as-is if it is not present in the context in any way
myContext.compactIri('http://xmlns.com/foaf/0.1/name');
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/`.
myContext.compactIri('http://vocab.org/something', true);

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

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

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

Getting the raw normalized context

The output of ContextParser#parse is a JsonLdContextNormalized object that represents the normalized context and exposes convenience functions such as expandTerm and compactIri.

In some cases, you may want to store the raw normalized JSON-LD context, e.g. caching to a file. For this, you can invoke the JsonLdContextNormalized#getContextRaw function as follows:

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

Afterwards, you can load this raw context into a new JsonLdContextNormalized context:

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

const myNewContext = new JsonLdContextNormalized(myRawJsonLdContext);
// Call functions such as myNewContext.expandTerm(...)

Advanced

This library exposes many operations that are useful to parse and handle a JSON-LD context. For this, the static functions on Util and ContextParser can be used.

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.