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.

This document is a very early attempt at a primer. It is very incomplete and should not be relied upon. Any comments and suggestions are welcome and can be sent to the JSON-LD mailing list.

Introduction

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 lined 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 linked data the are processing into easily manipulatable JSON data.

Examples Theme

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#
The URL of the vocabulary. Abbreviated as store in CURIES.
http://store.example.com/
The fictitious "Links Bike Shop". Abbreviated as links in CURIES.
store:Store
A store type. Instances have descriptive and product properties.
store:Product
A product for sale. Instances have descriptive, category, price, and availability properties.
store:Category
A product category type. Instances have descriptive properties.
store:product
A store:Store property linking to a store:Product.
store:category
A store:Product property linking to a store:Category.
store:price
A store:Product property linking to a price.
store:stock
A store:Product property linking to the quantity of the product in stock.

Example: "Links Bike Shop"

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:

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/"
    }
}

Use Cases

The following use cases are motivating in the design of JSON-LD.

Linked Data Processing

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.

Conversion to Known Format

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.

Data Sources

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.

Example: Linked Data Format Independence

FIXME: same triples in JSON-LD, RDFa, Microdata, triples

Framing

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.

Example: Basic Framing

FIXME: ex of simple frame features

Example: Alternate Views

FIXME: multiple ex of different views into the same source data

Putting It All Together

Example: ?

FIXME: more complex example