Repository files navigation

This library is an implementation of theJSON-LD specification inJavaScript.

JSON, as specified inRFC7159, is a simple language for representingobjects on the Web. Linked Data is a way of describing content acrossdifferent documents or Web sites. Web resources are described usingIRIs, and typically are dereferencable entities that may be used to findmore information, creating a "Web of Knowledge".JSON-LD is intendedto be a simple publishing method for expressing not only Linked Data inJSON, but for adding semantics to existing JSON.

JSON-LD is designed as a light-weight syntax that can be used to expressLinked Data. It is primarily intended to be a way to express Linked Datain JavaScript and other Web-based programming environments. It is alsouseful when building interoperable Web Services and when storing LinkedData in JSON-based document storage engines. It is practical anddesigned to be as simple as possible, utilizing the large number of JSONparsers and existing code that is in use today. It is designed to beable to express key-value pairs, RDF data,RDFa data,Microformats data, andMicrodata. That is, it supports everymajor Web-based structured data model in use today.

The syntax does not require many applications to change their JSON, buteasily add meaning by adding context in a way that is either in-band orout-of-band. The syntax is designed to not disturb already deployedsystems running on JSON, but provide a smooth migration path from JSONto JSON with added semantics. Finally, the format is intended to be fastto parse, fast to generate, stream-based and document-based processingcompatible, and require a very small memory footprint in order to operate.

This library aims to conform with the following:

• JSON-LD 1.0,W3C Recommendation,2014-01-16, and anyerrata
• JSON-LD 1.0 Processing Algorithms and API,W3C Recommendation,2014-01-16, and anyerrata
• JSON-LD 1.0 Framing,Unofficial Draft,2012-08-30
• JSON-LD 1.1,Draft Community Group Report,2018-06-07 ornewer
• JSON-LD 1.1 Processing Algorithms and API,Draft Community Group Report,2018-06-07 ornewer
• JSON-LD 1.1 Framing,Draft Community Group Report,2018-06-07 ornewer
• Community Grouptest suite

TheJSON-LD Working Group is now developing JSON-LD 1.1. Libraryupdates to conform with newer specifications will happen as features stabilizeand development time and resources permit.

• JSON-LD 1.1,W3C Working Draft,2018-12-14 ornewer
• JSON-LD 1.1 Processing Algorithms and API,W3C Working Draft,2018-12-14 ornewer
• JSON-LD 1.1 Framing,W3C Working Draft,2018-12-14 ornewer
• Working Grouptest suite

Thetest runner is often updated to note or skip newer tests that are notyet supported.

npm install jsonld

constjsonld=require('jsonld');

npm install jsonld

Use your favorite bundling technology (webpack,Rollup, etc) todirectly bundle your code that loadsjsonld. Note that you will need supportfor ES2017+ code.

The built npm package includes bundled code suitable for use in browsers. Twoversions are provided:

• ./dist/jsonld.min.js: A version built for wide compatibility with modernand older browsers. Includes many polyfills and code transformations and islarger and less efficient.
• ./dist/jsonld.esm.min.js: A version built for features available inbrowsers that support ES Modules. Fewer polyfills and transformations arerequired making the code smaller and more efficient.

The two bundles can be used at the same to to allow modern browsers to usenewer code. Lookup usingscript tags withtype="module" andnomodule.

Also see thewebpack.config.js if you would like to make a custom bundle forspecific targets.

npm install jsonld

Use your favorite technology to loadnode_modules/dist/jsonld.min.js.

To useCDNJS include this script tag:

<scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/jsonld/1.0.0/jsonld.min.js"></script>

Checkhttps://cdnjs.com/libraries/jsonld for the latest available version.

To usejsDeliver include this script tag:

<scriptsrc="https://cdn.jsdelivr.net/npm/jsonld@1.0.0/dist/jsonld.min.js"></script>

Seehttps://www.jsdelivr.com/package/npm/jsonld for the latest available version.

To useunpkg include this script tag:

<scriptsrc="https://unpkg.com/jsonld@1.0.0/dist/jsonld.min.js"></script>

Seehttps://unpkg.com/jsonld/ for the latest available version.

jspm install npm:jsonld

import*asjsonldfrom'jsonld';// orimport{promises}from'jsonld';// orimport{JsonLdProcessor}from'jsonld';

For specialized use cases there is an optionalrdf-canonize-native packageavailable which provides a native implementation forcanonize(). It is usedby installing the package and setting theuseNative option ofcanonize() totrue. Before using this mode it ishighly recommended to run benchmarkssince the JavaScript implementation is often faster and the bindings addtoolchain complexity.

npm install jsonldnpm install rdf-canonize-native

Example data and context used throughout examples below:

constdoc={"http://schema.org/name":"Manu Sporny","http://schema.org/url":{"@id":"http://manu.sporny.org/"},"http://schema.org/image":{"@id":"http://manu.sporny.org/images/manu.png"}};constcontext={"name":"http://schema.org/name","homepage":{"@id":"http://schema.org/url","@type":"@id"},"image":{"@id":"http://schema.org/image","@type":"@id"}};

// compact a document according to a particular contextconstcompacted=awaitjsonld.compact(doc,context);console.log(JSON.stringify(compacted,null,2));/* Output:{  "@context": {...},  "name": "Manu Sporny",  "homepage": "http://manu.sporny.org/",  "image": "http://manu.sporny.org/images/manu.png"}*/// compact using URLsconstcompacted=awaitjsonld.compact('http://example.org/doc','http://example.org/context', ...);

// expand a document, removing its contextconstexpanded=awaitjsonld.expand(compacted);/* Output:{  "http://schema.org/name": [{"@value": "Manu Sporny"}],  "http://schema.org/url": [{"@id": "http://manu.sporny.org/"}],  "http://schema.org/image": [{"@id": "http://manu.sporny.org/images/manu.png"}]}*/// expand using URLsconstexpanded=awaitjsonld.expand('http://example.org/doc', ...);

// flatten a documentconstflattened=awaitjsonld.flatten(doc);// output has all deep-level trees flattened to the top-level

// frame a documentconstframed=awaitjsonld.frame(doc,frame);// output transformed into a particular tree structure per the given frame

// canonize (normalize) a document using the RDF Dataset Canonicalization Algorithm// (URDNA2015):constcanonized=awaitjsonld.canonize(doc,{algorithm:'URDNA2015',format:'application/n-quads'});// canonized is a string that is a canonical representation of the document// that can be used for hashing, comparison, etc.

// serialize a document to N-Quads (RDF)constnquads=awaitjsonld.toRDF(doc,{format:'application/n-quads'});// nquads is a string of N-Quads

// deserialize N-Quads (RDF) to JSON-LDconstdoc=awaitjsonld.fromRDF(nquads,{format:'application/n-quads'});// doc is JSON-LD

// register a custom synchronous RDF parserjsonld.registerRDFParser(contentType,input=>{// parse input to a jsonld.js RDF dataset object... and return itreturndataset;});// register a custom promise-based RDF parserjsonld.registerRDFParser(contentType,asyncinput=>{// parse input into a jsonld.js RDF dataset object...returnnewPromise(...);});

// how to override the default document loader with a custom one -- for// example, one that uses pre-loaded contexts:// define a mapping of context URL => context docconstCONTEXTS={"http://example.com":{"@context": ...}, ...};// grab the built-in Node.js doc loaderconstnodeDocumentLoader=jsonld.documentLoaders.node();// or grab the XHR one: jsonld.documentLoaders.xhr()// change the default document loaderconstcustomLoader=async(url,options)=>{if(urlinCONTEXTS){return{contextUrl:null,// this is for a context via a link headerdocument:CONTEXTS[url],// this is the actual document that was loadeddocumentUrl:url// this is the actual context URL after redirects};}// call the default documentLoaderreturnnodeDocumentLoader(url);};jsonld.documentLoader=customLoader;// alternatively, pass the custom loader for just a specific call:constcompacted=awaitjsonld.compact(doc,context,{documentLoader:customLoader});

It is recommended to set a defaultuser-agent header for Node.jsapplications. The default for the default Node.js document loader isjsonld.js.

A common use case is to avoid JSON-LD constructs that will result in lossybehavior. The JSON-LD specifications have notes about when data is dropped.This can be especially important when calling [canonize][] in order todigitally sign data. A special "safe mode" is available that will detect thesesituations and cause processing to fail.

Note: This mode is designed to be the common way that digital signing andsimilar applications use this library.

Thesafe options flag set totrue enables this behavior:

// expand a document in safe modeconstexpanded=awaitjsonld.expand(data,{safe:true});

This library includes a sample testing utility which may be used to verifythat changes to the processor maintain the correct output.

The main test suites are included in external repositories. Check out each ofthe following:

https://github.com/w3c/json-ld-apihttps://github.com/w3c/json-ld-framinghttps://github.com/json-ld/json-ld.orghttps://github.com/w3c/rdf-canon

They should be sibling directories of the jsonld.js directory or in atest-suites dir. To clone shallow copies into thetest-suites dir you canuse the following:

npm run fetch-test-suites

Node.js tests can be run with a simple command:

npm test

If you installed the test suites elsewhere, or wish to run other tests, usetheTESTS environment var:

TESTS="/tmp/org/test-suites /tmp/norm/tests" npm test

This feature can be used to run the older json-ld.org test suite:

TESTS=/tmp/json-ld.org/test-suite npm test

Browser testing can be done with Karma:

npm run test-karmanpm run test-karma -- --browsers Firefox,Chrome

Code coverage of node tests can be generated incoverage/:

npm run coverage

To display a full coverage report on the console from coverage data:

npm run coverage-report

The Mocha output reporter can be changed to min, dot, list, nyan, etc:

REPORTER=dot npm test

Remote context tests are also available:

# run the context server in the background or another terminalnode tests/remote-context-server.jsTESTS=`pwd`/tests npm test

To generate EARL reports:

# generate the EARL report for Node.jsEARL=earl-node.jsonld npm test# generate the EARL report for the browserEARL=earl-firefox.jsonld npm run test-karma -- --browser Firefox

To generate an EARL report with thejson-ld-api andjson-ld-framing testsas used on the officialJSON-LD Processor Conformance page

TESTS="`pwd`/../json-ld-api/tests `pwd`/../json-ld-framing/tests" EARL="jsonld-js-earl.jsonld" npm test

The EARL.jsonld output can be converted to.ttl using therdf tool:

rdf serialize jsonld-js-earl.jsonld --output-format turtle -o jsonld-js-earl.ttl

Optionally follow thereportinstructions togenerate the HTML report for inspection. Maintainers cansubmit updated results as needed.

Benchmarks can be created from any manifest that the test system supports.Use a command line with a test suite and a benchmark flag:

TESTS=/tmp/benchmark-manifest.jsonld BENCHMARK=1 npm test

EARL reports with benchmark data can be generated with an optional environmentdetails:

TESTS=`pwd`/../json-ld.org/benchmarks/b001-manifiest.jsonld BENCHMARK=1 EARL=earl-test.jsonld TEST_ENV=1 npm test

Seetests/test.js for moreTEST_ENV andBENCHMARK control and options.

These reports can be compared with thebenchmarks/compare/ tool and at theJSON-LD Benchmarks site.

• jsonld-cli: A command line interface tool calledjsonld that exposesmost of the basic jsonld.js API.
• jsonld-request: A module that can read data from stdin, URLs, and filesand in various formats and return JSON-LD.

The source code for the JavaScript implementation of the JSON-LD APIis available at:

https://github.com/digitalbazaar/jsonld.js

Commercial support for this library is available upon request fromDigital Bazaar:support@digitalbazaar.com