What really is JSON-LD?

JSON-LD, or JavaScript Object Notation for Linked Data, is a method of transporting Linked Data using JSON. It was a goal to require as little effort as possible from developers to transform their existing JSON to JSON-LD.

This allows data to be serialized in a way that is similar to traditional JSON. JSON-LD is designed around the concept of a “context” to provide additional mappings from JSON to an RDF model. The context links object properties in a JSON document to concepts in an ontology. In order to map the JSON-LD syntax to RDF, JSON-LD allows values to be coerced to a specified type or to be tagged with a language. A context can be embedded directly in a JSON-LD document or put into a separate file and referenced from different documents (from traditional JSON documents via an HTTP Link header).

The interesting thing about JSON as a representational format is that it is really composed of simple syntactic structures – arrays and dictionaries or hashes, simple string values. That’s the real simplicity there, and of course it derives from JavaScript – JavaScript Object Notation – so as a developer it makes great sense to use something like that when you’re feeding your web application. When you’re extracting data from a service into your web application it automatically just updates your JavaScript runtime; you can access it quite easily.

JSON-LD, then, really looks to leverage this, but adds a lot of what is otherwise missing in JSON. So JSON being a very simple structure – it has strings, it has keys, it has strings as values, where it can have objects or hashes as values – it is very convenient but it has no inherent meaning. It has only the meaning that the person that’s describing their API – or sometimes not describing it – put in it. What we were striving to do in JSON-LD is to be able to take advantage of that syntactic simplicity, but provide unambiguous meaning.

In Linked Data meaning is ascribed using URLs (IRIs). So if I see a URL – let’s say schema.org/name – that is defined to mean if used as a URL describing a property that is used for name. So that anyone that wants to know what it is can dereference the URL and find out that information. But using schema.org/name in a key within a JSON dictionary is obviously not very convenient.

How to recognise differences between JSON and JSON-LD?

It’s possible that you might not, actually. But typically you do because there’s the presence of various keys that use an @ sign – so @id or @type or @context. In fact context is the only one that you absolutely need. Everyone else you can actually alias away using the context – that’s the chicken-egg reason we didn’t allow context to be aliased.

For example:

It’s possible to not use a context, actually, if it’s provided separately. So you can, for instance, treat regular JSON as JSON-LD. If it’s served up with application/json, say, you can add a link header that allows you to find the associated context. And for some people that’s a nice compromise. The downside of that is that does divorce the actual JSON-LD file from the context.


Further Resources