---
tags: CWU
title: Notes on JSON-LD
description: A brief overview of the basic features of JSON-LD
---

# Notes on JSON-LD

## Table of Contents
[TOC]

## Introduction
`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.

### Resources Used

- [Internationalized Resource Identifier (IRI) Specification](https://tools.ietf.org/html/rfc3987)
- [Resource Description Framework (RDF) Specification](https://www.w3.org/TR/rdf11-concepts/)
- JavaScript Object Notation Linked Data (JSON-LD)
- [JSON-LD Specification](https://www.w3.org/TR/json-ld)
- [JSON-LD Token & Keyword cheat sheet](https://www.w3.org/TR/json-ld/#syntax-tokens-and-keywords)
- [JSON-LD Framing Specification](https://www.w3.org/TR/json-ld11-framing)
- [JSON-LD Playground](https://json-ld.org/playground/)
- Video explainers
- [Basic Introduction](https://www.youtube.com/watch?v=vioCbTo3C-4)
- [Core Markup](https://www.youtube.com/watch?v=UmvWk_TQ30A)
- [Compaction and Expansion](https://www.youtube.com/watch?v=Tm3fD89dqRE)
- [Linked Data Signatures](https://www.youtube.com/watch?v=Tm3fD89dqRE)

### Related Documents
- [Linked Data Proofs](/inzaVCAtSdWQxzmw8doNGg)

### Relevant Terminology
| 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. |

## Basic Keywords
### `@context`
In 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": "[phone]",
  "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,

#### Aliasing

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": "[phone]",
  "url": "http://www.janedoe.com"
}

The `@type` value (`Person`) can now also be accessed by using the `type` key.

#### Additional Keys
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](https://www.w3.org/TR/json-ld/#syntax-tokens-and-keywords) page.

### `@type`

There are two types in `JSON-LD`, **object types** and `data types`.

#### Object 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": "[phone]",
  "url": "http://www.janedoe.com"
}

#### Data Types
When the `@type` value contains a **data type**, it is used to specify how the data value should be interpreted.

### `@id`
The `@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](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.

## Relationships

{
  "@context": "http://schema.org/",
  "type": "Person",
  "name": "Jane Doe",
  "jobTitle": "Professor",
  "telephone": "[phone]",
  "url": "http://www.janedoe.com",
  "spouse": {
    "name": "Bob Bobberson",
    "jobTitle": "Professor",
    "telephone": "[phone]"
  }
}

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](schema.org/Person). 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.

## Graph Representation
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": "[phone]",
  "url": "http://www.janedoe.com",
  "spouse": {
    "name": "Bob Bobberson",
    "jobTitle": "Professor",
    "telephone": "[phone]"
  }
}

**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`.

## Resolving Relationship Types
You might have noticed that the example in the [Graph Representation](#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](schema.org/Person). When we look up the [definition of spouse](https://schema.org/spouse), we can see the expected value is also a [Person](schema.org/Person). Because this relationship is defined by the [Person context](schema.org/Person), the `JSON-LD` processor knows how to interpret the spouse object without the need for an explicit `@type` attribute.

## Compaction & Expansion
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:
1. It removes the `@context` key from the object, and adds its value to the `@type` value.
2. It replaces the `JSON object` keys with the appropriate **RDF referent**.
3. It replaces the value of the `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": "[phone]",
  "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": "[phone]"
      }
    ],
    "http://schema.org/url": [
      {
        "@id": "http://www.janedoe.com"
      }
    ]
  }
]

:::warning
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.
:::

## JSON-LD Flattening
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": "[phone]",
  "url": "http://www.janedoe.com",
  "spouse": {
    "name": "Bob Bobberson",
    "jobTitle": "Professor",
    "telephone": "[phone]"
  }
}

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](schema.org/Person). 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": "[phone]",
      "url": "http://www.janedoe.com"
    },
    {
      "id": "_:b1",
      "jobTitle": "Professor",
      "name": "Bob Bobbert",
      "telephone": "[phone]"
    }
  ]
}

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`.

## JSON-LD Framing
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"
  }
}