JSON-LD (or JavaScript Object Notation - Linked Data) is a mechanism that is used primarily for two use cases: providing context and creating decentralized references between data sets.
| Term | Description |
|---|---|
| JSON object | A plain JSON object |
| JSON-LD object | A JSON object that contains JSON-LD attributes |
| IRI | The Internationalized Resource Identifier (IRI) is an internet protocol standard which builds on the Uniform Resource Identifier (URI) protocol by greatly expanding the set of permitted characters. In the context of JSON-LD, IRIs are mainly used to specify RDFs. |
| RDF | The Resource Description Framework (RDF) is a framework for representing information in the Web. RDFs documents describe how a piece of data should be interpreted. RDFs are usually denoted by an IRI, in which case it's called the referent. |
@contextIn order to give context to JSON data, JSON-LD uses an object under the the @context key. This object is used to describe how the other values in the document should be interpreted. If the JSON-LD object contains a key called createdAt with a date value, the @context object tells you that this value is a date and how the date is being used (in this case to specify a creation date).
Instead of directly nesting the context object, the value of @context may also be a reference in the form of a URI. In this case, the URI is expected to point to a location that contains the context object that would otherwise be nested. The JSON-LD processor will then replace it's value with the actual object.
Take a look at this example:
{
"@context": "http://schema.org/Person",
"name": "Jane Doe",
"jobTitle": "Professor",
"telephone": "(425) 123-4567",
"url": "http://www.janedoe.com"
}
In the example above, the @context value tells us that there is a document at schema.org/Person that describes how the values of name, jobTitle, telephone and url should be interpreted. In this case the @context value contains a reference,
The context can also be used to specify other things such as aliasing. Aliasing is used to create alias mappings between two keys. Let's say you'd like to access the @type value by a more conventional JSON key, like the type key. You could achieve this by specifying this in the context as such:
{
"@context": {
"type": "@type",
},
"@type": "Person",
"name": "Jane Doe",
"jobTitle": "Professor",
"telephone": "(425) 123-4567",
"url": "http://www.janedoe.com"
}
The @type value (Person) can now also be accessed by using the type key.
Apart from the things mentioned above, the @context object may be used to specify additional context related information. A description of these can be found at the JSON-LD Token & Keyword page.
@typeThere are two types in JSON-LD, object types and data types.
When the @type value contains a object type, like for example Person, it's used to lookup a specific document that relates to the @context.
For example, the previous example is identical to the following, where the @type value will be expanded to schema.org/Person.
{
"@context": "http://schema.org",
"@type": "Person",
"name": "Jane Doe",
"jobTitle": "Professor",
"telephone": "(425) 123-4567",
"url": "http://www.janedoe.com"
}
When the @type value contains a data type, it is used to specify how the data value should be interpreted.
@idThe @id key is used to uniquely identify a node object that is being described in the document with an IRI or a blank node identifier. If a node only contains a @id property, it may be used to represent a node found somewhere else in the document.
An example:
{
"@context": {
...
"name": "http://schema.org/name"
},
"@id": "http://me.markus-lanthaler.com/",
"name": "Markus Lanthaler",
...
}
In the above example the @id property points to a document at http://me.markus-lanthaler.com. Although the object above only contains a name, the @id document can be used to retrieve additional information about Markus Lanthaler.
{
"@context": "http://schema.org/",
"type": "Person",
"name": "Jane Doe",
"jobTitle": "Professor",
"telephone": "(425) 123-4567",
"url": "http://www.janedoe.com",
"spouse": {
"name": "Bob Bobberson",
"jobTitle": "Professor",
"telephone": "(425) 321-7654"
}
}
The above example describes an object of type Person that is specified by a document that resides at schema.org/Person. This object also contains a spouse key that is used to define a relationship to another object. The JSON-LD processor knows that the data in the spouse object value should be interpreted as a Person object because the spouse key is defined by the Person context. The Person context tells the JSON-LD processor that the definition of spouse can be found at schema.org/spouse, which defines it as a Person object.
Because JSON-LD can also specify data relationships, it can be represented as a graph.
This object for example:
{
"@context": "http://schema.org/",
"@type": "Person",
"name": "Jane Doe",
"jobTitle": "Professor",
"telephone": "(425) 123-4567",
"url": "http://www.janedoe.com",
"spouse": {
"name": "Bob Bobberson",
"jobTitle": "Professor",
"telephone": "(425) 321-7654"
}
}
Can be represented as such:
digraph hierarchy {
// nodesep=1.0 // increases the separation between nodes
node [color=Red,fontname=Courier,shape=box]
edge [color=Blue, style=dashed]
root [color=magenta label="_0072386"]
spouse [color=green shape=oval]
type [color=blue label="@type:\nPerson"]
jobTitle1 [label="jobTitle:\nProfessor"]
jobTitle2 [label="jobTitle:\nProfessor"]
spouse->{"name:\nBob Bobbert" jobTitle1, "telephone:\n(425) 321-7654"}
root->{type "name:\nJane Doe" jobTitle2, "telephone:\n(425) 123-4567" "url:\nhttp://www.janedoe.com", spouse}
}
In the graph above we see that our root object (_0072386) has a relationship to another object under the spouse key. There is nothing inherently special about the graph representation above. However, it helps to think in terms of graphs when working with JSON-LD.
You might have noticed that the example in the Graph Representation section doesn't have a @type attribute specified for the spouse relationship. This is because spouse is an attribute that is defined in the Person context. When we look up the definition of spouse, we can see the expected value is also a Person. Because this relationship is defined by the Person context, the JSON-LD processor knows how to interpret the spouse object without the need for an explicit @type attribute.
The examples so far are compact representations. Compact representations make it easier for humans to work with JSON-LD data, but for computers however, this is not ideal. Therefore a JSON-LD processor will expand the the compacted version to a expanded representation.
When expanding a JSON-LD object, the JSON-LD processor does two things:
@context key from the object, and adds its value to the @type value.JSON object keys with the appropriate RDF referent.JSON object with an object and adds the value inside that object under the @value key.For example:
The following compact representation:
{
"@context": "http://schema.org/",
"@type": "Person",
"name": "Jane Doe",
"jobTitle": "Professor",
"telephone": "(425) 123-4567",
"url": "http://www.janedoe.com"
}
Is expanded to this expanded representation:
[
{
"@type": [
"http://schema.org/Person"
],
"http://schema.org/jobTitle": [
{
"@value": "Professor"
}
],
"http://schema.org/name": [
{
"@value": "Jane Doe"
}
],
"http://schema.org/telephone": [
{
"@value": "(425) 123-4567"
}
],
"http://schema.org/url": [
{
"@id": "http://www.janedoe.com"
}
]
}
]
You may have noticed that the JSON-LD processor did not only replace the values by objects while expanding, but actually has put that object into an array. This is because the RDF allows for multiple values for these keys.
In JSON-LD, objects are often nested to describe relationships.
Take the following (compacted) example:
{
"@context": "http://schema.org/",
"type": "Person",
"name": "Jane Doe",
"jobTitle": "Professor",
"telephone": "(425) 123-4567",
"url": "http://www.janedoe.com",
"spouse": {
"name": "Bob Bobberson",
"jobTitle": "Professor",
"telephone": "(425) 321-7654"
}
}
The above example describes an object of type Person that is specified by a document that resides at schema.org/Person. This object also contains a spouse key that is used to define a relationship to another object. The JSON-LD processor knows that the data in the spouse object value should be interpreted as a Person object because the spouse key is defined by the Person context. The Person context tells the JSON-LD processor that the definition of spouse can be found at schema.org/spouse, which defines it as a Person object.
The above example is quite simple, but imagine we have a huge JSON-LD document with hundreds of relationships. This document would possibly contain a large amount of nested objects which is not ideal for computer processing.
To overcome this, JSON-LD processors can do something called flattening. When a JSON-LD object is flattened, the processor creates a one-dimensional array of all the objects, and provides these objects with a generated id value. The id value is then used to reference to the object from other objects.
When flattened, the above example looks as follows:
{
"@context": "http://schema.org/",
"@graph": [
{
"id": "_:b0",
"type": "Person",
"jobTitle": "Professor",
"name": "Jane Doe",
"spouse": {
"id": "_:b1"
},
"telephone": "(425) 123-4567",
"url": "http://www.janedoe.com"
},
{
"id": "_:b1",
"jobTitle": "Professor",
"name": "Bob Bobbert",
"telephone": "(425) 321-7654"
}
]
}
When the JSON-LD processor 'unflattens' the object, it will simply replace the value of spouse with the corresponding object that refers to the value of id.
A framing document specifies an embedding structure that tells the processor how a flattened JSON-LD object should be reconstructed.
Take the following framing document for example:
{
"@context": {
"@version": 1.1,
"@vocab": "http://example.org/"
},
"@type": "Library",
"contains": {
"@type": "Book",
"contains": {
"@type": "Chapter"
}
}
}
Using the framing document above, the processor is able to reconstruct the following flattened JSON-LD object:
{
"@context": {
"@vocab": "http://example.org/",
"contains": {"@type": "@id"}
},
"@graph": [{
"@id": "http://example.org/library",
"@type": "Library",
"contains": "http://example.org/library/the-republic"
}, {
"@id": "http://example.org/library/the-republic",
"@type": "Book",
"creator": "Plato",
"title": "The Republic",
"contains": "http://example.org/library/the-republic#introduction"
}, {
"@id": "http://example.org/library/the-republic#introduction",
"@type": "Chapter",
"description": "An introductory chapter on The Republic.",
"title": "The Introduction"
}]
}
Resulting in the following 'unflattened' representation:
{
"@context": {
"@version": 1.1,
"@vocab": "http://example.org/"
},
"@id": "http://example.org/library",
"@type": "Library",
"contains": {
"@id": "http://example.org/library/the-republic",
"@type": "Book",
"contains": {
"@id": "http://example.org/library/the-republic#introduction",
"@type": "Chapter",
"description": "An introductory chapter on The Republic.",
"title": "The Introduction"
},
"creator": "Plato",
"title": "The Republic"
}
}
-
Any changes
Be notified of any changes
-
Mention me
Be notified of mention me
-
Unsubscribe
Subscribe