Nautilus: Pelagic Mollusc

    jsonld-context-parser
    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 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:

    • 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('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:

    • 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: '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:

    • 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 `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.

    Install

    npm i jsonld-context-parser

    DownloadsWeekly Downloads

    11,477

    Version

    2.1.5

    License

    MIT

    Unpacked Size

    106 kB

    Total Files

    21

    Last publish

    Collaborators

    • rubensworks