- Notifications
You must be signed in to change notification settings - Fork0
A JSON-LD Processor and API implementation in JavaScript
License
RalfBarkow/jsonld.js
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
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 pass thetest suite and 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.1,Draft Community Group Report,2018-02-15 ornewer
- JSON-LD 1.1 Processing Algorithms and API,Draft Community Group Report,2018-02-15 ornewer
npm install jsonldconstjsonld=require('jsonld');
npm install jsonldUse 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:jsonldimport*asjsonldfrom'jsonld';// orimport{promises}from'jsonld';// orimport{JsonLdProcessor}from'jsonld';
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 contextjsonld.compact(doc,context,function(err,compacted){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 URLsjsonld.compact('http://example.org/doc','http://example.org/context', ...);// or using promisesconstcompacted=awaitjsonld.compact(doc,context);
// expand a document, removing its contextjsonld.expand(compacted,function(err,expanded){/* 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 URLsjsonld.expand('http://example.org/doc', ...);// or using promisesconstexpanded=awaitjsonld.expand(doc);
// flatten a documentjsonld.flatten(doc,(err,flattened)=>{// all deep-level trees flattened to the top-level});// or using promisesconstflattened=awaitjsonld.flatten(doc);
// frame a documentjsonld.frame(doc,frame,(err,framed)=>{// document transformed into a particular tree structure per the given frame});// or using promisesconstframed=awaitjsonld.frame(doc,frame);
canonize (normalize)
// canonize (normalize) a document using the RDF Dataset Normalization Algorithm// (URDNA2015), see:jsonld.canonize(doc,{algorithm:'URDNA2015',format:'application/n-quads'},(err,canonized)=>{// canonized is a string that is a canonical representation of the document// that can be used for hashing, comparison, etc.});// or using promisesconstcanonized=awaitjsonld.canonize(doc,{format:'application/n-quads'});
// serialize a document to N-Quads (RDF)jsonld.toRDF(doc,{format:'application/n-quads'},(err,nquads)=>{// nquads is a string of N-Quads});// or using promisesconstrdf=awaitjsonld.toRDF(doc,{format:'application/n-quads'});
// deserialize N-Quads (RDF) to JSON-LDjsonld.fromRDF(nquads,{format:'application/n-quads'},(err,doc)=>{// doc is JSON-LD});// or using promisesconstdoc=awaitjsonld.fromRDF(nquads,{format:'application/n-quads'});
// register a custom async-callback-based RDF parserjsonld.registerRDFParser(contentType,(input,callback)=>{// parse input to a jsonld.js RDF dataset object...callback(err,dataset);});// 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 loader using the callback API// (you can also do this using the promise-based API, return a promise instead// of using a callback)constcustomLoader=(url,callback)=>{if(urlinCONTEXTS){returncallback(null,{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 underlining documentLoader using the callback API.nodeDocumentLoader(url,callback);/* Note: By default, the node.js document loader uses a callback, but browser-based document loaders (xhr or jquery) return promises if they are supported (or polyfilled) in the browser. This behavior can be controlled with the 'usePromise' option when constructing the document loader. For example: jsonld.documentLoaders.xhr({usePromise: false}); */};jsonld.documentLoader=customLoader;// alternatively, pass the custom loader for just a specific call:constcompacted=awaitjsonld.compact(doc,context,{documentLoader:customLoader});
- jsonld-cli: A command line interface tool called
jsonldthat 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.
Commercial support for this library is available upon request fromDigital Bazaar:support@digitalbazaar.com
The source code for the JavaScript implementation of the JSON-LD APIis available at:
http://github.com/digitalbazaar/jsonld.js
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/json-ld/json-ld.orghttps://github.com/json-ld/normalizationThey 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-suitesNode.js tests can be run with a simple command:
npm testIf you installed the test suites elsewhere, or wish to run other tests, usetheJSONLD_TESTS environment var:
JSONLD_TESTS="/tmp/org/test-suites /tmp/norm/tests" npm testBrowser testing can be done with Karma:
npm run test-karmanpm run test-karma -- --browsers Firefox,ChromeCode coverage of node tests can be generated incoverage/:
npm run coverageTo display a full coverage report on the console from coverage data:
npm run coverage-reportThe Mocha output reporter can be changed to min, dot, list, nyan, etc:
REPORTER=dot npm testRemote context tests are also available:
# run the context server in the background or another terminalnode tests/remote-context-server.jsJSONLD_TESTS=./tests npm testTo 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 FirefoxBenchmarks can be created from any manifest that the test system supports.Use a command line with a test suite and a benchmark flag:
JSONLD_TESTS=/tmp/benchmark-manifest.jsonld JSONLD_BENCHMARK=1 npm testAbout
A JSON-LD Processor and API implementation in JavaScript
Resources
License
Stars
Watchers
Forks
Packages0
Languages
- JavaScript99.9%
- Shell0.1%