SolidusPod

What is JSON-LD, and where does a pod actually use it?

JSON-LD is JSON that is also RDF. We emit exactly one such document and we process none of them. The W3C specified it, the Solid community's server handles it, and our own status is specified, not implemented.

The idea

Take ordinary JSON, add a @context that maps its keys to globally unique URLs, and the same document is now a set of RDF triples, the model is here.

{
  "@context": "https://schema.org/",
  "name": "Ada",
  "knows": { "name": "Bob" }
}

Nothing about the JSON changed. A consumer that does not care about linked data reads it as JSON and ignores the context. A consumer that does care expands it into triples and merges it with data from somewhere else.

That backwards compatibility is the whole design, and it is why JSON-LD, rather than Turtle, is the format most people meet first.

The trap it sets

A document can look like ordinary JSON and behave like RDF, and the difference only appears when somebody processes it.

  • Two keys that look identical can mean different things, if the contexts differ.
  • A context is a URL, and a URL can move, change or disappear. A document whose meaning depends on fetching a remote context has a dependency most readers do not notice.
  • "We support JSON-LD" is ambiguous. It can mean we can serve a file with a @context in it, or we expand, compact and canonicalise. Those are wildly different amounts of engineering, and the phrase does not distinguish them.

That last one is the reason this page exists, because it applies to us.

What we actually do, measured in both directions

A search of our code for JSON-LD matches 21 files. That looks like an implementation. It is not.

Reading them shows @context URL strings, .jsonld file-extension routing, a served document, and comments. A JSON-LD library import: zero. An expand, compact or canonicalise call: zero, with a control confirming the search style finds real implementations elsewhere.

So: no JSON-LD processing exists in our code. The lexicon's status, specified, not implemented, is accurate, and we checked it rather than trusting it.

And the other half, which is equally true: we do serve one real JSON-LD document.

$ curl -s https://pod.solidus.network/clientid.jsonld
  200  application/ld+json
  {"@context":["https://www.w3.org/ns/solid/oidc-context.jsonld"],
   "client_id":"https://pod.solidus.network/clientid.jsonld", ...}

That is a Solid Client ID document, how an application identifies itself in the Solid login flow (the flow is here). It is a fixed shape we emit, not a document we parse.

A made-up .jsonld path returns 401 rather than 200, so the document above is genuinely served rather than anything ending in .jsonld being answered.

Where a pod meets JSON-LD in practice

  • The client ID document, above. Emitted by us, consumed by an identity provider.
  • Credentials stored in a pod. A W3C verifiable credential in JSON-LD form is, by construction, linked data, so it lands in a pod as an RDF resource rather than an opaque blob.
  • Content negotiation. The deployed server will hand you application/ld+json if you ask for it, and returns text/plain for a nonsense type, which is the control showing negotiation is real.

All three are the Solid server's behaviour or a static document. None of them is a JSON-LD processor, and we are not going to let the word "supports" blur that.

The honest version of "the platform supports JSON-LD"

Our own internal description says the platform supports RDF including JSON-LD. That is true of the Community Solid Server we run: the Solid community's reference implementation, which we did not write. Saying that first is the accurate credit, and it is the same distinction as on /rdf and /turtle.

If you need JSON-LD expansion or canonicalisation, do not rely on us for it. Use a library. The ecosystem's are mature and ours does not exist.

What this does not settle

A @context makes a document interpretable. It does not make it true, and it does not say who may read it. Those are credentials and access control respectively, and both have their own honest status.

Keep reading

What is JSON-LD, and where does a pod actually use it? · Solidus