jsonld-context-parser
v3.0.0
Published
Parses JSON-LD contexts
Downloads
172,376
Maintainers
Readme
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. - 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 inremoteContexts
, 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.