diff --git a/primer/index.php b/primer/index.php deleted file mode 100644 index a7e5ecc4a..000000000 --- a/primer/index.php +++ /dev/null @@ -1,133 +0,0 @@ - - - - JSON-LD - JSON for Linking Data - - - - - - - - - - - - - - - - - - - -
-
-
- - - - - - JSON-LD logo JSON-LD -
- -
- -
-
-
-
-
-
-
-

Primers

-

The following primers are sorted in most recent to - least recent order:

-
    -
  • Latest
    • - -htmlcode; - -if(is_dir('ED')) -{ - $editorsDrafts = scandir('ED', 1); - - foreach($editorsDrafts as $draft) - { - if($draft != "." and $draft != "..") - { - print("
  • $draft
    • "); - } - } -} - -print <<< htmlcode -
-
-
-
- -
- - - -htmlcode; - -?> - diff --git a/primer/latest/index.html b/primer/latest/index.html deleted file mode 100644 index 14ae6a160..000000000 --- a/primer/latest/index.html +++ /dev/null @@ -1,403 +0,0 @@ - - - -JSON-LD Primer - - - - - - - - -
- -

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

- -
-

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

- -
-
- - -