js-ipld-jsonld

JavaScript implementation of a JSON-LD IPLD format

Hash-linking all the world's data is great, but sometimes you encounter graphs that really are circular. We can still traverse these by property-path, but only if we address nodes by identifiers other than their hash.

JSON-LD is a (recent!) web standard for encoding Linked Data™, and it's the growing default for serializing graphs on the web. This is an IPLD format for JSON-LD documents that resolves (potentially circular) paths within the graph, and defines a JSON-LD-compliant scheme for linking back to the greater IPLD world.

Table of Contents

• Install
• Usage
  • No multicodec entry
  • No slashes in property names
  • Match three cases for root documents
  • Index into every array-like structure
  • Linking back to the outside world
• Contribute
• License

Install

$ npm install ipld-jsonld --save

Usage

Assuming you have a reference ipld to an IPLD Resolver (at the moment you can sneak into node._ipld from any js-ipfs node), you can add support for the JSON-LD format manually:

const {util, resolver} = require("ipld-jsonld")

console.log(resolver.multicodec) // "jsonld"

ipld.support.add(resolver.multicodec, resolver, util)

const your_document = {...some_jsonld}

ipld.put(your_document, {format: "jsonld"}, (err, cid) => {
  console.log(cid.codec) // "jsonld"
  ipld.get(cid, "graph/path/to/traverse", (err, result) => {
    if (err) console.error(err)
    else {
      const {value, remainderPath} = result
      ...
    }
  })
})

This package comes with several major caveats:

No multicodec entry

JSON-LD isn't an official multicodec, so it doesn't have an entry in the multicodec table. This means you can't serialize cid to a base-encoded string, because it doesn't know which prefix bytes correspond to the "jsonld" codec.

If you want to go rogue and fake an entry, you can install the multicodec package and insert them yourself:

const codecVarints = require("multicodec/src/varint-table")
const codecNames = require("multicodec/src/name-table")
...
const hex = "77" // or other free byte
const codec = "jsonld"
codecVarints[codec] = Buffer.from(hex, "hex")
codecNames[hex] = codec
...
const b58 = cid.toBaseEncodedString() // zeRd8...

No slashes in property names

JSON-LD requires property names and identifiers to be IRIs, which tend to be forward-slash dense. Slashes in properties are not supported; paths are sent straight to parts = path.split("/"). Fortunately, JSON-LD also promotes the heavy use of the @context property with colon-prefixed term expansion. You should do this; it's good practice anyway.

// Bad:
const bad = {
	"http://schema.org/name": "John Doe",
}
// Good:
const good = {
	"@context": { name: "http://schema.org/name" },
	name: "John Doe",
}
// Better:
const better = {
	"@context": { s: "http://schema.org/" },
	"s:name": "John Doe",
	"s:telephone": "(012) 345-6789",
}
// Best:
const best = {
	"@context": { "@vocab": "http://schema.org/" },
	name: "John Doe",
	telephone: "(012) 345-6789",
}
// Worst, for now (fetches from network on every deserialization):
const worst = {
	"@context": "http://example.com/my-context.json",
	name: "John Doe",
}

Match three cases for root documents

A JSON-LD document has three "root" formats:

// All three cases: every node has optional @context.

// Case 1: the root document is a node.
// <cid>/name => "Jane Doe"
const case1 = {
  "@context": {...}
  "name": "Jane Doe"
}

// Case 2: the root document is an array of nodes.
// <cid>/0/foo => "bar"
const case2 = [
  {
    "@context": {...},
    "foo": "bar"
  },
  ...
]

// Case 3: the root document is a @context/@graph object,
// where @context is optional and @graph is an array of nodes
// <cid>/w:Q42/s:name => "Douglas Adams"
const case3 = {
  "@context": {
    "w": "http://www.wikidata.org/wiki/",
    "s": "http://schema.org/"
  },
  "@graph": [
    {
      "@id": "w:Q42"
      "s:name": "Douglas Adams"
    },
    ...
  ]
}

The first element of the path is interpreted differently depending on the document's format.

• Case 1: a property name of the root node
• Case 2: an ingeter index of one of the root nodes
• Case 3: the @id of a node in the @graph array

The discrepency between cases 2 and 3 is somewhat arbitrary, but motivated by the suspicion that users are more likely to know their target's @id than its index when serialized (for Case 3), but expect a top-level array to be addressed by index (for Case 2).

Note that since JSON-LD requires every @id value to be an IRI, successfully indexing a Case 3 format document requires the use of a top-level @context to rename @id values (this difficulty is further motivation for the Case 2/3 discrepency, since Case 2 has no top-level context at all).

Index into every array-like structure

JSON-LD uses arrays to indicate multiple values, and also has @list and @set wrappers to explicitly denote ordered-ness and unordered-ness. Until a better idea comes along, you have to index into every array-like element (including @sets) with an integer.

const jsonld = {
  "@context": { "@vocab": "http://schema.org/" },
  "name": {
    "@set": ["John Doe", "JDoe", "JD"]
  }
}
const cid = await ipfs.dag.put(jsonld, {format: "jsonld"})
const names = await ipfs.dag.get(cid, "name")
// { value: [ 'John Doe', 'JDoe', 'JD' ], remainderPath: '' } <-- the @set gets unwrapped
const jd = await ipfs.dag.get(cid, "name/2")
// { value: 'JD', remainderPath: '' }

Index maps link back to the outside world

The IPLD spec defines a link object to be an object of the form {"/": <base58-encoded-cid>}, but foreign, non-IRI keys like "/" aren't included the JSON-LD spec (they're not invalid, but JSON-LD processors are required to ignore them).

Fortunately, JSON-LD defines a structure called an index map to solve exactly this issue: signalling to JSON-LD processors that a particular key should not be discarded. This is done with a special @index key in one of two ways:

// Method 1: including {@index, @value} manually
const method1 = {
	...stuff,
	externalLink: {
		"@index": "/",
		"@value": "<base58-encoded-cid>",
	},
}
// Method 2: using an @container in the context
const method2 = {
	"@context": {
		...context,
		externalLink: { "@container": "@index" },
	},
	...stuff,
	externalLink: { "/": "<base58-encoded-cid>" },
}

Note that in method 2, we can use a literal IPLD link as a property value (!!), but we have to declare in the context which properties we expect to be links. Again, this has its tradeoffs, but supports the JSON-LD pattern of relying on a well-articulated context to simplify the graph itself.

So we can run an example like this:

const cid = await ipfs.dag.put({foo: 4}, {format: "dag-cbor"})
const b58 = cid.toBaseEncodedString() // zdpuB3WAXUM4VJpSRKFarS2GnwBqbFKLSdt8DB3bgfLdVCvrs
const jsonld = {
  "@context": {
    "@vocab": "http://schema.org/",
    "bar": { "@container": "@index" },
  },
  "@id": "http://people.com/jane_doe",
  "@type": "Person",
  "name": "Jane Doe",
  "spouse": {
    "@id": "http://people.com/john_doe",
    "@type": "Person",
    "name": "John Doe",
    "spouse": { "@id": "http://people.com/jane_doe" },
    "bar": { "/": `${b58}/foo`},
  }
}
const cid2 = await ipfs.dag.put(jsonld, {format: "jsonld"})
const baz = await ipfs.dag.get(cid2, "spouse/spouse/spouse/bar")
// { value: 4, remainderPath: "" }

Contribute

This is an incredibly early and premature project, but if you're interested in contributing or just have any ideas or advice in general, please open an issue!

License

MIT