Nautilus: Pelagic Mollusc

    TypeScript icon, indicating that this package has built-in type declarations

    2.1.5 • Public • Published

    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:

    • 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.
    • Convert @container string and array values to a hash-based value.
    • 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 context.expandTerm.
    • IRI compacting with the context.compactIri.

    Example input (with base IRI set to

        "@vocab": "",
        "npmd": "",
        "p": { "@id": "pred1", "@language": "nl" }

    With containing:

      "xsd": "",
      "name": ""

    Example output:

      "@base": "",
      "@vocab": "",
      "npmd": "",
      "p": { "@id": "", "@language": "nl" },
      "xsd": "",
      "name": ""


    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.



    Create a new parser

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

    Optionally, the following constructor options can be passed:

    • documentLoader: An optional document loader that should be used for fetching external JSON-LD contexts. Custom loaders must implement the IDocumentLoader interface (Default: new FetchDocumentLoader())
    • skipValidation: By default, JSON-LD contexts will be validated. This can be disabled by setting this option to true. (Default: false)
    • expandContentTypeToBase: If @type inside the context may be expanded via @base is @vocab is set to null. (Default: false)
    • remoteContextsDepthLimit: The maximum number of remote contexts that can be fetched recursively. (Default: 32)
    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('');

    by an non-normalized context:

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

    or by an array of mixed contexts or URLs:

    const myContext = await myParser.parse([
      { ... },

    Optionally, the following parsing options can be passed:

    • baseIRI: An initial default base IRI. (Default: '')
    • parentContext: An optional context to inherit from. (Default: null)
    • external: If the given context is being loaded from an external URL. (Default: false)
    • processingMode: The JSON-LD version that the context should be parsed with. (Default: 1.1)
    • 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)
    • ignoreProtection: If checks for validating term protection should be skipped. (Default: false)
    • minimalProcessing: If the context should only be parsed and validated, without performing normalizations and other modifications. (Default: false)
    • ignoreRemoteScopedContexts: If true, a remote context that will be looked up, and is already contained in remoteContexts, will not emit an error but will produce an empty context. (Default: false)
    • remoteContexts: A hash containing all remote contexts that have been looked up before. (Default: false)
    const myContext = await myParser.parse({ ... }, {
      baseIRI: '',
      parentContext: {},
      external: true,
      processingMode: 1.0,
      normalizeLanguageTags: true,
      ignoreProtection: true,
      minimalProcessing: true,
      ignoreRemoteScopedContexts: true,
      remoteContexts: {
        '': 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.
    // Expands if `foaf` is present in the context
    // Returns the URI as-is
    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('', true);
    Expansion options

    Optionally, the following options can be passed for expansion:

    • allowPrefixNonGenDelims: If compact IRI prefixes can end with any kind of character in simple term definitions, instead of only the default gen-delim characters (:,/,?,#,[,],@). (Default: false)
    • allowPrefixForcing: If compact IRI prefixes ending with a non-gen-delim character can be forced as a prefix using @prefix: true. (Default: false)
    • allowVocabRelativeToBase: If @vocab values are allowed contain IRIs relative to @base. (Default: true)
    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 ``.
    // Compacts to `prefix:name` if `"prefix": ""` is in the context
    // Returns the URI as-is if it is not present in the context in any way
    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 ``.
    myContext.compactIri('', true);
    // Compacts to `prefix:name` if `"prefix": ""` is in the context
    myContext.compactIri('', true);
    // Compacts to `term` if `"term": ""` is in the context
    myContext.compactIri('', true);
    // Returns the URI as-is if it is not present in the context in any way
    myContext.compactIri('', 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('');
    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(...)


    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.


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


    $ jsonld-context-parse url
    $ jsonld-context-parse file path/to/context.jsonld
    $ jsonld-context-parse arg '{ "xsd": "" }'


    This software is written by Ruben Taelman.

    This code is released under the MIT license.


    npm i jsonld-context-parser

    DownloadsWeekly Downloads






    Unpacked Size

    106 kB

    Total Files


    Last publish


    • rubensworks