This document attempts to provide a gentle introduction and examples of JSON-LD and to be a companion to the JSON-LD specification.
This document is an experimental work in progress.
JSON-LD [[!JSON-LD]] combines the simplicity, power, and web ubiquity of JSON [[!RFC4627]] with the concepts of Linked Data [[LINKED-DATA]] [[JSON-LD-REQUIREMENTS]]. This document attempts to provide an introduction to the concepts and usage of JSON-LD as well as some examples of how it can be utilized in practice.
The requirements for JSON-LD can be found in [[JSON-LD-REQUIREMENTS]] document and provide some basic definitions for concepts and terms used here. The full specification for JSON-LD can be found in [[JSON-LD]] and is the basis for the examples given here. Please refer to these documents as needed.
The semantic web and linked data are a foundation of knowledge representation. What follows is a high-level view for the purposes of this document. A full discussion of these concepts is out of the scope of this document but see [[JSON-LD-REQUIREMENTS]] for a better description of these concepts. Linked data systems are most often built using the concept of "triples". A single triple is built from a subject, a property, and a value. A collection of these triples can form a graph of data.
Applications processing linked data can do so in a number of ways. One is to access the raw triples. This is very flexible but often is cumbersome. Another is to use some form of graph processing API, of which many variations exist. Another is to create a tree view from a portion of the graph.
JSON-LD combines these features. At a low-level it provides a standardized way to represent linked data in JSON. However, it has been found that much of the linked data that is practically processed in JSON can be converted into tree structures that are more natural to handle. Many programming languages even offer native natural access to tree-like structures and no special APIs are required.
Converting linked data graphs to easily accessible tree structures solves one problem of linked data processing. Another is that in many cases the components of a triple are represented as IRIs. Using long IRIs everywhere to access data is very flexible and has many benefits but from a programming view point is rather unwieldy.
JSON-LD provides the ability to add "context" to the data and "coerce" values into forms that are easier to process. In fact, the end result of good JSON-LD usage is data structures that look like simple JSON but are in fact full linked data graphs. This provides a good deal of power for application developers to convert the linked data they are processing into easily manipulatable JSON data.
Throughout this document the examples are based on a theme of processing data for a online store. Linked data uses IRIs to represent types and properties. The examples here will use two root URLs as well as a few simple types and properties. A real linked data system should use a common standard such as the GoodRelations vocabulary.
http://ns.example.com/store#store in CURIES.http://store.example.com/links in CURIES.store:Storestore:Productstore:Categorystore:productstore:Store property linking to a store:Product.store:categorystore:Product property linking to a store:Category.store:pricestore:Product property linking to a price.store:stockstore:Product property linking to the quantity of the product in stock.FIXME: How should this be organized? Start with basic JSON, add LD? Start with pieces, combine into full doc? Something else?
Let's start by building up a fictitious bike store called "Links Bike Shop".
We've already got our bike store setup at
http://store.example.com/ and are using linked data principles.
Here's some of the URLs:
http://store.example.com/: The home page of the store.http://store.example.com/products/links-swift-chain: A chain product.http://store.example.com/products/links-speedy-lube: A chain lube product.We want to start creating some linked data for this fictitious store and start with rough JSON data on the store itself.
{
"@id": "http://store.example.com/",
"@type": "Store",
"name": "Links Bike Shop",
"description": "The most \"linked\" bike store on earth!"
}
That was easy, right? Next let's create some rough data for our two premier products.
{
"@id": "http://store.example.com/products/links-swift-chain",
"@type": "Product",
"name": "Links Swift Chain",
"description": "A fine chain with many links.",
"category": [
"http://store.example.com/categories/parts",
"http://store.example.com/categories/chains"
],
"price": "10.00",
"stock": 10
}
{
"@id": "http://store.example.com/products/links-speedy-lube",
"@type": "Product",
"name": "Links Speedy Lube",
"description": "Lubricant for your chain links.",
"category": [
"http://store.example.com/categories/lubes",
"http://store.example.com/categories/chains"
],
"price": "5.00",
"stock": 20
}
To make this into a full JSON-LD document we combine the data, add a
@context, and adjust some values.
{
"@id": "http://store.example.com/",
"@type": "Store",
"name": "Links Bike Shop",
"description": "The most \"linked\" bike store on earth!",
"product": [
{
"@id": "p:links-swift-chain",
"@type": "Product",
"name": "Links Swift Chain",
"description": "A fine chain with many links.",
"category": ["cat:parts", "cat:chains"],
"price": "10.00",
"stock": 10
},
{
"@id": "p:links-speedy-lube",
"@type": "Product",
"name": "Links Speedy Lube",
"description": "Lubricant for your chain links.",
"category": ["cat:lube", "cat:chains"],
"price": "5.00",
"stock": 20
}
],
"@context": {
"Store": "http://ns.example.com/store#Store",
"Product": "http://ns.example.com/store#Product",
"product": "http://ns.example.com/store#product",
"category":
{
"@id": "http://ns.example.com/store#category",
"@type": "@id"
},
"price": "http://ns.example.com/store#price",
"stock": "http://ns.example.com/store#stock",
"name": "http://purl.org/dc/terms/title",
"description": "http://purl.org/dc/terms/description",
"p": "http://store.example.com/products/",
"cat": "http://store.example.com/category/"
}
}
The following use cases are motivating in the design of JSON-LD.
JSON-LD provides the ability to take linked data from many different sources and present it to an application in an easy to process JSON format. In many cases the transformation from a linked data graph to a JSON tree makes the data appear to just be a simple JSON structure.
Linked data may be input in a form that an application is not prepared to handle. JSON-LD offers the ability to convert linked data into a form that each application can specify on its own.
JSON-LD is not dependent on any particular source of data. It is possible to convert many types of semantic web formats into JSON-LD. This is one of the classic benefits of the semantic web and its foundation of triples. Depending on the application and where it is used, a source of data may come from many places:
A source-specific processor must convert the data into JSON-LD. In most cases if you can convert a data format into a form of triples, then the conversion into an expanded form of JSON-LD is trivial. Once this has taken place, it is possible to use framing and other JSON-LD processing concepts to convert the data into a form which is easier to process at the application level. This ability allows you process linked data provided in many formats in a standardized way.
FIXME: same triples in JSON-LD, RDFa, Microdata, triples
Many applications wish to access data as if it is a simple tree structure. This is natural in many programming languages and often comes for free without a specialized API. The flexibility of the JSON-LD format and linked data it represents does come with a problem.
FIXME: ex of simple frame features
FIXME: multiple ex of different views into the same source data
FIXME: more complex example