npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

jsonld-context-parser

v3.0.0

Published

Parses JSON-LD contexts

Downloads

172,376

Readme

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.