1.1How to Read this Document

This section is non-normative.

This document is a detailed specification for a serialization of LinkedData in JSON. The document is primarily intended for the following audiences:

• Software developers that want to encode Linked Data in a way that is cross-language compatible via JSON.
• Software developers that want to understand the design decisions and language syntax for JSON-LD.
• Software developers that want to implement processors and APIs for JSON-LD.

This specification does not describe the programming interfaces for theJSON-LD Syntax. The specification that describes the programming interfacesfor JSON-LD documents is the JSON-LD Application Programming Interface[JSON-LD-API].

To understand the basics in this specification you must first be familiar withJSON, which is detailed in [RFC4627].

JSON [RFC4627] defines several terms which are used throughout this document:

JSON object

An object structure is represented as a pair of curly brackets surrounding zero or more name-value pairs. A name is astring. A single colon comes after each name, separating the name from the value. A single comma separates a value from a following name. The names within an objectshould be unique.

array

In JSON, an array is anordered sequence of zero or more values. An array is represented as square brackets surrounding zero or more values that are separated by commas. While JSON-LD uses the same array representation as JSON, the collection isunordered by default. While order is preserved in regular JSON arrays, it is not in regular JSON-LD arrays unless specific markup is provided (seeSets and Lists).

string

A string is a sequence of zero or more Unicode characters, wrapped in double quotes, using backslash escapes (if necessary). A character is represented as a single character string.

number

A number is similar to that used in most programming languages, except that the octal and hexadecimal formats are not used and that leading zeros are not allowed.

true andfalse

Values that are used to express one of two possible boolean states.

null

The null value is used to make the JSON-LD processor "forget" any previously defined JSON key that is associated with the null value. If a previous definition doesn't exist, the entire key-value is ignored. If a previous definition of the key does exist, the previous definition is undefined.

subject definition

AJSON object used to represent asubject and one or more properties of that subject. AJSON object is a subject definition if it does not contain they keys@value,@list or@set and it has one or more keys other than@id.

subject reference

AJSON object used to reference a subject having only the@id key.

3.1Linking Data

The following definition forLinked Data is the one that willbe used for this specification.

1. Linked Data is a set of documents, each containing a representation of alinked data graph.
2. Alinked data graph is an unordered labeled directed graph, where nodes aresubjects orobjects, and edges are labeled usingproperties.
3. Asubject is any node in alinked data graph with at least one outgoing edge.
4. Asubjectshould be labeled with anIRI (an Internationalized Resource Identifier as described in [RFC3987]).
5. Anobject is a node in alinked data graph with at least one incoming edge.
6. Anobjectmay be labeled with anIRI or a label that is not anIRI such as plain text, internationalized text, or a strictly-typed data value.
7. A nodemay be asubject and anobject at the same time.
8. Aproperty is the label on an edge in alinked data graph.
9. Apropertyshould be anIRI.
10. AnIRI that is a label in alinked data graphshould be dereferencable to aLinked Data document describing the labeledsubject,property orobject.

Note that the definition forLinked Data above is silent on thetopic ofunlabeled nodes. Nevertheless, this specification allows for the expressionofunlabeled nodes, as most graph-based data sets on the Web contain a numberof associated nodes that are not named and thus are not directlyde-referenceable.

JSON-LD defines a mechanism to map JSON terms, i.e., keys and values, to IRIs. This does not meanthat JSON-LD requires every key or value to be anIRI, but rather ensures thatkeys and values can be mapped to IRIs if the developer desires to transformtheir data intoLinked Data. There are a few techniques that can ensurethat developers will generate good Linked Data for the Web. JSON-LDformalizes those techniques.

We will be using the following JSON markup as the example for therest of this section:

{  "name": "Manu Sporny",  "homepage": "http://manu.sporny.org/",  "depiction": "http://twitter.com/account/profile_image/manusporny"}

{  "@context":  {    "name": "http://xmlns.com/foaf/0.1/name",    "depiction":    {      "@id": "http://xmlns.com/foaf/0.1/depiction",      "@type": "@id"    },    "homepage":    {      "@id": "http://xmlns.com/foaf/0.1/homepage",      "@type": "@id"    },  }}

{"@context": "http://json-ld.org/contexts/person.jsonld",  "name": "Manu Sporny",  "homepage": "http://manu.sporny.org/",  "depiction": "http://twitter.com/account/profile_image/manusporny"}

{"@context":  {    "name": "http://xmlns.com/foaf/0.1/name",    "depiction":    {      "@id": "http://xmlns.com/foaf/0.1/depiction",      "@type": "@id"    },    "homepage":    {      "@id": "http://xmlns.com/foaf/0.1/homepage",      "@type": "@id"    },  },  "name": "Manu Sporny",  "homepage": "http://manu.sporny.org/",  "depiction": "http://twitter.com/account/profile_image/manusporny"}

{"@context": [    "http://json-ld.org/contexts/person.jsonld",    {      "pic": "http://xmlns.com/foaf/0.1/depiction"    }  ],  "name": "Manu Sporny",  "homepage": "http://manu.sporny.org/","pic": "http://twitter.com/account/profile_image/manusporny"}

{  "http://xmlns.com/foaf/0.1/name": "Manu Sporny",  "http://xmlns.com/foaf/0.1/homepage": "http://manu.sporny.org"  "http://xmlns.com/foaf/0.1/depiction": "http://twitter.com/account/profile_image/manusporny"}

3.2IRIs

IRIs are fundamental toLinked Dataas that is how mostsubjects, allproperties and manyobjects areidentified.IRIs can be expressed in a variety of different waysin JSON-LD.

1. Except within acontext definition,terms in the key position in aJSON object that have a mapping to anabsoluteIRI or anotherterm in theactive context are expanded to anIRI by JSON-LD processors.
2. AnIRI is generated for thestring value specified using@id or@type.
3. AnIRI is generated for thestring value of any key for which there arecoercion rules in effect that identify the value as an@id.

IRIs may be represented as anabsoluteIRI, arelativeIRI, aterm, or acompactIRI.

AnabsoluteIRI is defined in [RFC3987] containing ascheme along withpath and optionalquery andfragment segments. ArelativeIRI is anIRI that is relative to some otherabsoluteIRI. In JSON-LD allrelativeIRIs are resolved relative to thebaseIRI associated with the document (typically, the directory that contains the document or the document itself).

IRIs can be expressed directly in the key position like so:

{...  "http://xmlns.com/foaf/0.1/name": "Manu Sporny",...}

In the example above, the keyhttp://xmlns.com/foaf/0.1/name is interpreted as anIRI because it contains a colon (:) and the 'http'prefix does not exist in the context.

Term expansion occurs for IRIs if the value matches aterm defined within theactive context:

{  "@context":  {    "name": "http://xmlns.com/foaf/0.1/name"...  },  "name": "Manu Sporny",  "status": "trollin'",...}

Terms are case sensitive, andmust be matched using a case-sensitive comparison.

JSON keys that do not expand to an absoluteIRI are ignored, or removedin some cases, by the [JSON-LD-API]. However, JSON keys that do not includea mapping in thecontext are still considered valid expressionsin JSON-LD documents - the keys just don't have any machine-readable,semantic meaning.

Prefixes are expanded when the form of the value is acompactIRI represented as aprefix:suffix combination, and the prefix matches aterm defined within theactive context:

{  "@context":  {    "foaf": "http://xmlns.com/foaf/0.1/"...  },  "foaf:name": "Manu Sporny",...}

foaf:name above will automatically expand out to theIRIhttp://xmlns.com/foaf/0.1/name. SeeCompact IRIs for more details.

AnIRI is generated when a JSON object is used in thevalue position that contains an@id keyword:

{...  "homepage": { "@id": "http://manu.sporny.org" }...}

If typecoercion rules are specified in the@context fora particularterm or propertyIRI, anIRI is generated:

{  "@context":  {    ...    "homepage":    {      "@id": "http://xmlns.com/foaf/0.1/homepage",      "@type": "@id"    }    ...  }...  "homepage": "http://manu.sporny.org/",...}

In the example above, even though the valuehttp://manu.sporny.org/ is expressed as a JSONstring, the typecoercion rules will transformthe value into anIRI when processed by a JSON-LD Processor.

3.3Identifying the Subject

To be able to externally reference nodes in a graph, it is important that each node has an unambiguous identifier.IRIs are a fundamental concept ofLinked Data, and nodes should have a de-referencable identifier used to name and locate them. For nodes to be truly linked, de-referencing the identifier should result in a representation of that node (for example, using a URL to retrieve a web page). Associating anIRI with a node tells an application that the returned document contains a description of the node requested.

JSON-LD documents may also contain descriptions of other nodes, so it is necessary to be able to uniquely identify each node which may be externally referenced.

Asubject of aJSON object is a node identified using the@id key. The subject is thefirst piece of information needed by the JSON-LD processor in order tocreate the (subject, property, object) tuple, also known as a triple.

{  "@context":  {    ...    "homepage":    {      "@id": "http://xmlns.com/foaf/0.1/homepage",      "@type": "@id"    }    ...  },  "@id": "http://example.org/people#joebob",  "homepage": "http://manu.sporny.org/",...}

The example above would set the subject to theIRIhttp://example.org/people#joebob.

AJSON object used to define property values is called asubject definition.Subject definitions do not require an@id. Asubject definition that does not contain an@id property defines properties of anunlabeled node.

3.4Specifying the Type

The type of a particular subject can be specified using the@typekeyword. Specifying the type in this way will generate atriple of the form (subject, type, type-IRI). To be consideredLinked Data, typesmust be uniquely identified byanIRI.

{...  "@id": "http://example.org/people#joebob",  "@type": "http://xmlns.com/foaf/0.1/Person",...}

3.5String Internationalization

At times, it is important to annotate astring with its language. In JSON-LD this is possible in a variety of ways. Firstly, it is possible to define a default language for a JSON-LD document by setting the@language key in the@context or in aterm definition:

{"@context":  {    ...    "@language": "ja"  },  "name":"花澄",  "occupation":"科学者"}

The example above would associate theja language code with the twostrings花澄 and科学者. Languagesmust be well-formed language tags according to [BCP47].

It is possible to override the default language by using the expandedform of a value:

{  "@context": {    ...    "@language": "ja"  },  "name": "花澄",  "occupation":{    "@value": "Scientist",    "@language": "en"  }}

It is also possible to override the default language or specify a plainvalue by omitting the@language tag or setting it tonull when expressing the expanded value:

{  "@context": {    ...    "@language": "ja"  },  "name":{    "@value": "Frank"  },  "occupation": {    "@value": "Ninja",    "@language": "en"  },  "speciality": "手裏剣"}

To clear the default language for a subtree,@language canbe set tonull in alocal context as follows:

{  "@context": {    ...    "@language": "ja"  },  "name": "花澄",  "details": {    "@context": {      "@language": null    },    "occupation": "Ninja"  }}

3.6JSON-LD Syntax

A JSON-LD document is first, and foremost, a JSON document (as defined in [RFC5988]), and any syntactically correct JSON documentmust be processed by a conforming JSON-LD processor. However, JSON-LD describes a specific syntax to use for expressing Linked Data. This includes the use of specific keywords, as identified inSyntax Tokens and Keywords for expressingsubject definitions, values, and thecontext. SeeAppendix A for authoring guidelines and a BNF description of JSON-LD.

4.1Compact IRIs

Terms inLinked Data documents may draw from a number of differentvocabularies. At times, declaring every single term that a document uses can require the developer to declare tens, if not hundreds of potentialvocabularyterms that are used across an application. This is a concern for at least two reasons: the first is the cognitive load on the developer of remembering all of theterms, and the second is the serialized size of thecontext if it is specified inline. In order to address these issues, the concept of acompactIRI is introduced.

AcompactIRI is a way of expressing anIRI using aprefix andsuffix separated by a colon (:) which is similar to theCURIE Syntax in [RDFA-CORE]. Theprefix is aterm taken from theactive context and is a short string identifying a particularIRI in a JSON-LD document. For example, the prefixfoaf may be used as a short hand for the Friend-of-a-Friend vocabulary, which is identified using theIRIhttp://xmlns.com/foaf/0.1/. A developer may append any of the FOAFvocabulary terms to the end of the prefix to specify a short-hand version of theabsoluteIRI for thevocabulary term. For example,foaf:name would be expanded out to theIRIhttp://xmlns.com/foaf/0.1/name. Instead of having to remember and type out the entireIRI, the developer can instead use the prefix in their JSON-LD markup.

Terms are interpreted ascompactIRIs if they contain at least one colon and the first colon is not followed by two slashes (//, as inhttp://example.com). To generate the fullIRI, the value is first split into aprefix andsuffix at the first occurrence of a colon (:). If theactive context contains a term mapping forprefix, anIRI is generated by prepending the mappedprefix to the (possibly empty)suffix using textual concatenation. If no prefix mapping is defined, the value is interpreted as anabsoluteIRI. If the prefix is an underscore (_), theIRI remains unchanged. This effectively means that every term containing a colon will be interpreted by a JSON-LD processor as anIRI.

Consider the following example:

{  "@context":  {"dc": "http://purl.org/dc/elements/1.1/","ex": "http://example.org/vocab#"  },  "@id": "http://example.org/library",  "@type":"ex:Library","ex:contains":  {    "@id": "http://example.org/library/the-republic",    "@type":"ex:Book","dc:creator": "Plato","dc:title": "The Republic","ex:contains":    {      "@id": "http://example.org/library/the-republic#introduction",      "@type":"ex:Chapter","dc:description": "An introductory chapter on The Republic.","dc:title": "The Introduction"    }  }}

In this example, two differentvocabularies are referred to using prefixes. Those prefixes are then used as type and property values using the compactIRIprefix:suffix notation.

It's also possible to use compact IRIs within the context as shown in the following example:

{  "@context":  {    "xsd": "http://www.w3.org/2001/XMLSchema#",    "foaf": "http://xmlns.com/foaf/0.1/","foaf:homepage": { "@type": "@id" },    "picture": { "@id":"foaf:depiction", "@type": "@id" }  },  "@id": "http://me.markus-lanthaler.com/",  "@type": "foaf:Person",  "foaf:name": "Markus Lanthaler",  "foaf:homepage": "http://www.markus-lanthaler.com/",  "picture": "http://twitter.com/account/profile_image/markuslanthaler"}

4.2Typed Values

A value with an associated type, also known as atyped value, is indicated by associating a value with anIRI which indicates the value's type. Typed values may be expressed in JSON-LD in two ways:

1. By utilizing the@typekeyword when defining aterm within a@context section.
2. By utilizing the expanded form for specifying objects.

The first example uses the@type keyword to associate atype with a particularterm in the@context:

{"@context":  {    "modified":    {      "@id": "http://purl.org/dc/terms/modified",      "@type": "http://www.w3.org/2001/XMLSchema#dateTime"    }  },...  "modified": "2010-05-29T14:17:39+02:00",...}

Themodified key's value above is automatically type coerced to adatetime value because of the information specified in the@context.

The second example uses the expanded form of setting the type informationin the body of a JSON-LD document:

{  "@context":  {    "modified":    {      "@id": "http://purl.org/dc/terms/modified"    }  },...  "modified":{    "@value": "2010-05-29T14:17:39+02:00",    "@type": "http://www.w3.org/2001/XMLSchema#dateTime"  }...}

Both examples above would generate an object with the value of2010-05-29T14:17:39+02:00 and the type ofhttp://www.w3.org/2001/XMLSchema#dateTime. Note that it isalso possible to use aterm or acompactIRI toexpress the value of a type.

4.3External Contexts

Authors may choose to declare JSON-LDcontexts in externaldocuments to promote re-use of contexts as well as reduce the size of JSON-LDdocuments.

In order to use an external context, an authormust specify anIRIto a valid JSON-LD document. The referenced documentmust have atop-levelsubject definition. The value of any@context keywithin that object is substituted for theIRI within the referencing documentto have the same effect as if the value were specified inline within thereferencing document.

The following example demonstrates the use of an external context:

{"@context": "http://json-ld.org/contexts/person.jsonld",  "name": "Manu Sporny",  "homepage": "http://manu.sporny.org/",  "depiction": "http://twitter.com/account/profile_image/manusporny"}

Authors may also import multiple contexts or a combination of externaland local contexts by specifying a list of contexts:

{"@context":  [    "http://json-ld.org/contexts/person.jsonld",    {      "foaf": "http://xmlns.com/foaf/0.1/"    },    "http://json-ld.org/contexts/event.jsonld"  ],  "name": "Manu Sporny",  "homepage": "http://manu.sporny.org/",  "foaf:depiction": "http://twitter.com/account/profile_image/manusporny","celebrates":  {    "@type": "Event",    "description": "International Talk Like a Pirate Day",    "date": "R/2011-09-19"  }}

Each context in a list will be evaluated in-order. Duplicate mappings amongthecontextsmust be overwritten on a last-defined-overridesbasis. The context listmust contain either de-referenceableIRIsorJSON objects that conform to thecontext syntaxas described in this document.

An authormay nest contexts withinsubject definitions, with themore deeply nested contexts overriding the values in previously definedcontexts:

{"@context":  {    "name": "http://example.com/person#name",    "details": "http://example.com/person#details"  },  "name": "Markus Lanthaler",  ...  "details":  {"@context": {      "name": "http://example.com/organization#name"    },    "name": "Graz University of Technology"  }}

In the example above, thename prefix is overridden in themore deeply nesteddetails structure. Note that this israrely a good authoring practice and is typically used when theJSON object has legacy applications using the structure of the object.

External JSON-LD context documentsmay contain extra information locatedoutside of the@context key, such asdocumentation about theprefixes declared in the document.When importing a@context value from an external JSON-LD contextdocument, any extra information contained outside of the@context valuemust be discarded. It isalsorecommended that a human-readable document is served as well toexplain the correct usage of the JSON-LD context document.

4.4Referencing Contexts from JSON Documents

Ordinary JSON documents can be transformed into JSON-LD documents by referencingto an external JSON-LDcontext in an HTTP Link Header. Doing thisallows JSON to be unambiguously machine-readable without requiring developers todrastically change their workflow and provides an upgrade path for existinginfrastructure without breaking existing clients that rely on theapplication/jsonmedia type.

In order to use an external context with an ordinary JSON document, an authormust specify anIRI to a valid JSON-LD document in an HTTP LinkHeader [RFC5988] using thedescribedby link relation.The referenced documentmust have a top-levelsubject definition. The@context subtree within that object is added to the top-levelsubject definition of the referencing document. If anarray is at the top-level of thereferencing document and its items aresubject definitions, the@contextsubtree is added to allarray items. All extra information located outsideof the@context subtree in the referenced documentmust bediscarded.

The following example demonstrates the use of an external context with anordinary JSON document:

GET /ordinary-json-document.json HTTP/1.1Host: example.comAccept: application/ld+json,application/json,*/*;q=0.1====================================HTTP/1.0 200 OK...Content-Type:application/jsonLink: <http://json-ld.org/contexts/person.jsonld>; rel="describedby"; type="application/ld+json"{  "name": "Markus Lanthaler",  "homepage": "http://www.markus-lanthaler.com/",  "depiction": "http://twitter.com/account/profile_image/markuslanthaler"}

4.5Expanded Term Definition

Within acontext definition,termsmay be defined using an expanded notation to allow for additional information associated with the term to be specified (see alsoType Coercion andSets and Lists).

Instead of using a string representation of anIRI, theIRImay bespecified using aJSON object having an@id key.The value of the@id keymust be either aterm, acompactIRI, or anabsoluteIRI. Suchan object is called asubject reference.

{  "@context":  {    "foaf":{ "@id": "http://xmlns.com/foaf/0.1/" },    "name":{ "@id": "http://xmlns.com/foaf/0.1/name" },    "homepage":{ "@id": "foaf:homepage" },    "depiction":{ "@id": "foaf:depiction" }  },  "name": "Manu Sporny",  "homepage": "http://manu.sporny.org/",  "depiction": "http://twitter.com/account/profile_image/manusporny"}

This allows additional information to be associated with the term. Thismay be used forType Coercion,Sets and Lists), or to associate language information with a term as shown in the following example:

{  "@context": {    ...    "ex": "http://example.com/",    "@language": "ja",    "name": { "@id": "ex:name","@language": null },    "occupation": { "@id": "ex:occupation" },    "occupation_en": { "@id": "ex:occupation","@language": "en" },    "occupation_cs": { "@id": "ex:occupation","@language": "cs" }  },"name": "Yagyū Muneyoshi",  "occupation": "忍者",  "occupation_en": "Ninja",  "occupation_cs": "Nindža",  ...}

The example above would associate忍者 with the specified default language codeja,Ninja with the language codeen, andNindža with the language codecs. The value ofname,Yagyū Muneyoshi wouldn't be associated with any language code since@language was reset tonull in the expanded term definition.

Expanded termsmay also be defined usingcompact IRIs orabsolute IRIs as keys. If the definition does not include an@id key, the expandedIRI is determined by performing expansion of the key within the current active context. This mechanism is mainly used to associate type or language information with acompactIRI or anabsoluteIRI.

4.6Type Coercion

JSON-LD supports the coercion of values to particular data types.Typecoercion allows someone deploying JSON-LD to coerce the incoming oroutgoing values to the proper data type based on a mapping of data typeIRIs toterms. Using type coercion, value representation is preserved without requiringthe data type to be specified with each piece of data.

Type coercion is specified within anexpanded term definition using the@type key. The value of this key represents a typeIRI andmust take the form of aterm,compactIRI,absoluteIRI, or thekeyword@id. Specifying@id indicates that within the body of a JSON-LD document, a string value of aterm coerced to@id is to be interpreted as anIRI.

Terms orcompact IRIs used as the value of a@type keymay be defined within the same context. This means that one may specify aterm likexsd and then usexsd:integer within the same context definition - the JSON-LD processor will be able to determine the proper expansion forxsd:integer.

The example below demonstrates how a JSON-LD author can coerce values totyped values, IRIs and lists.

{  "@context":  {    "xsd": "http://www.w3.org/2001/XMLSchema#",    "name": "http://xmlns.com/foaf/0.1/name",    "age":{      "@id": "http://xmlns.com/foaf/0.1/age",      "@type": "xsd:integer"    },    "homepage":{      "@id": "http://xmlns.com/foaf/0.1/homepage",      "@type": "@id",      "@container": "@list"    }  },  "name": "John Smith",  "age":"41",  "homepage":[    "http://personal.example.org/",    "http://work.example.com/jsmith/"  ]}

The example above would generate the following Turtle:

@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .[ foaf:name "John Smith";  foaf:age  "41"^^xsd:integer;  foaf:homepage ( <http://personal.example.org/> <http://work.example.com/jsmith/> )] .

Terms may also be defined usingabsolute IRIs orcompact IRIs. This allows coercion rules to be applied to keys which are not represented as a simpleterm. For example:

{  "@context":  {"foaf": "http://xmlns.com/foaf/0.1/",    "foaf:age":    {      "@type": "xsd:integer"    },    "foaf:homepage":{      "@type": "@id"    }  },  "foaf:name": "John Smith",  "foaf:age":"41",  "foaf:homepage":[    "http://personal.example.org/",    "http://work.example.com/jsmith/"  ]}

In this case the@id definition is optional, but if it does exist, thecompactIRI orIRI is treated as a term (not aprefix:suffix construct) so that the actual definition of aprefix becomes unnecessary.

Type coercion is performed using the unexpanded value of the key, whichmust have an exact match for an entry in theactive context.

4.7IRI Expansion Within a Context

In general, normalIRI expansion rules apply anywhere anIRI is expected (seeIRIs). Within acontext definition, this can mean that terms defined within the contextmay also be used within that context as long as there are no circular dependencies. For example, it is common to use thexsd namespace when definingtyped values:

{  "@context":  {"xsd": "http://www.w3.org/2001/XMLSchema#",    "name": "http://xmlns.com/foaf/0.1/name",    "age":    {      "@id": "http://xmlns.com/foaf/0.1/age",      "@type":"xsd:integer"    },    "homepage":    {      "@id": "http://xmlns.com/foaf/0.1/homepage",      "@type": "@id"    }  },  ...}

In this example, thexsdterm is defined and used as aprefix for the@type coercion of theage property.

Termsmay also be used when defining theIRI of anotherterm:

{  "@context":  {"foaf": "http://xmlns.com/foaf/0.1/",    "xsd": "http://www.w3.org/2001/XMLSchema#",    "name":"foaf:name",    "age":    {      "@id":"foaf:age",      "@type": "xsd:integer"    },    "homepage":    {      "@id":"foaf:homepage",      "@type": "@id"    }  },  ...}

Compact IRIs andIRIsmay be used on the left-hand side of aterm definition.

{  "@context":  {"foaf": "http://xmlns.com/foaf/0.1/",    "xsd": "http://www.w3.org/2001/XMLSchema#",    "name": "foaf:name",    "foaf:age":    {      "@type": "xsd:integer"    },    "foaf:homepage":{      "@type": "@id"    }  },  ...}

In this example, thecompactIRI form is used in two differentways.In the first approach,foaf:age declares both theIRI for the term (using short-form) as well as the@type associated with theterm. In the secondapproach, only the@type associated with theterm isspecified. The JSON-LD processor will derive the fullIRI forfoaf:homepage by looking up thefoafprefix in thecontext.

Absolute IRIsmay also be used in the key position in acontext:

{  "@context":  {    "foaf": "http://xmlns.com/foaf/0.1/",    "xsd": "http://www.w3.org/2001/XMLSchema#",    "name": "foaf:name",    "foaf:age":    {      "@id": "foaf:age",      "@type": "xsd:integer"    },    "http://xmlns.com/foaf/0.1/homepage":    {      "@type": "@id"    }  },  ...}

In order for theabsoluteIRI to match above, theabsoluteIRImust alsobe used in the JSON-LD document. Also note thatfoaf:homepagewill not use the{ "@type": "@id" } declaration becausefoaf:homepage is not the same ashttp://xmlns.com/foaf/0.1/homepage. That is, a JSON-LDprocessor will use direct string comparison when looking upterms in acontext before it applies theprefix lookup mechanism.

The only exception for using terms in thecontext is that theymust not be used in a circular manner. That is, a definition ofterm-1must not depend on the definition ofterm-2 ifterm-2 also depends onterm-1. For example, the followingcontext definition is illegal:

{  "@context":  {"term1": "term2:foo",    "term2": "term1:bar"  },  ...}

4.8Sets and Lists

A JSON-LD author can express multiple values in a compact way by usingarrays. Since graphs do not describe ordering for links between nodes, arrays in JSON-LD do not provide an ordering of the listedobjects by default. This is exactly the opposite from regular JSON arrays, which are ordered by default. For example, consider the following simple document:

{...  "@id": "http://example.org/people#joebob",  "nick":[ "joe", "bob", "jaybee" ],...}

The markup shown above would result in three triples being generated, each relating the subject to an individualobject, with no inherent order:

<http://example.org/people#joebob>   <http://xmlns.com/foaf/0.1/nick>      "joe" .<http://example.org/people#joebob>   <http://xmlns.com/foaf/0.1/nick>      "bob" .<http://example.org/people#joebob>   <http://xmlns.com/foaf/0.1/nick>      "jaybee" .

Multiple values may also be expressed using the expanded form:

{  "@id": "http://example.org/articles/8",  "dc:title":  [    {      "@value": "Das Kapital",      "@language": "de"    },    {      "@value": "Capital",      "@language": "en"    }  ]}

The markup shown above would generate the following triples, again with no inherent order:

<http://example.org/articles/8>   <http://purl.org/dc/terms/title>      "Das Kapital"@de .<http://example.org/articles/8>   <http://purl.org/dc/terms/title>      "Capital"@en .

As the notion of ordered collections is rather important in data modeling, it is useful to have specific language support. In JSON-LD, a list may be represented using the@listkeyword as follows:

{...  "@id": "http://example.org/people#joebob",  "foaf:nick":{    "@list": [ "joe", "bob", "jaybee" ]  },...}

This describes the use of thisarray as being ordered, and order is maintained when processing a document. If every use of a given multi-valued property is a list, this may be abbreviated by setting@container to@list in thecontext:

{"@context":  {    ...    "nick":    {      "@id": "http://xmlns.com/foaf/0.1/nick",      "@container": "@list"    }  },...  "@id": "http://example.org/people#joebob",  "nick":[ "joe", "bob", "jaybee" ],...}

Similarly to@list, there exists thekeyword@set to describe unordered sets. While its use in the body of a JSON-LD document represents just syntactic sugar thatmust be optimized away when processing the document, it is very helpful when used within the context of a document. Values of terms associated with a@set or@list container are always represented in the form of anarray - even if there is just a single value that would otherwise be optimized to a non-array form in acompacted document. This makes post-processing of the data easier as the data is always in array form, even if the array only contains a single value.

4.9Embedding

Objectembedding is a JSON-LD feature that allows an author to usesubject definitions asproperty values. This is a commonly used mechanism for creating a parent-child relationship between twosubjects.

The example shows two subjects related by a property from the first subject:

{...  "name": "Manu Sporny",  "knows":  {    "@type": "Person",    "name": "Gregg Kellogg",  }...}

Asubject definition, like the one used above,may be used in any value position in the body of a JSON-LD document.

4.10Named Graphs

The@graphkeyword is used to express a set of JSON-LDsubject definitions that may not be directly related to one another through a property. The mechanism may also be used whereembedding is not desirable to the application. For example:

{  "@context": ...,  "@graph":  [    {      "@id": "http://manu.sporny.org/i/public",      "@type": "foaf:Person",      "name": "Manu Sporny",      "knows": "http://greggkellogg.net/foaf#me"    },    {      "@id": "http://greggkellogg.net/foaf#me",      "@type": "foaf:Person",      "name": "Gregg Kellogg",      "knows": "http://manu.sporny.org/i/public"    }  ]}

In this case, embedding doesn't work as eachsubject definition references the other. Using the@graphkeyword allows multiple resources to be defined within anarray, and allows the use of a sharedcontext. When used in aJSON object that is not otherwise asubject definition, this describes resources in thedefault graph. This is equivalent to using multiplesubject definitions in array and defining the@context within eachsubject definition:

[  {"@context": ...,    "@id": "http://manu.sporny.org/i/public",    "@type": "foaf:Person",    "name": "Manu Sporny",    "knows": "http://greggkellogg.net/foaf#me"  },  {"@context": ...,    "@id": "http://greggkellogg.net/foaf#me",    "@type": "foaf:Person",    "name": "Gregg Kellogg",    "knows": "http://manu.sporny.org/i/public"  }]

JSON-LD allows you toname things on the Web by assigning an@id to them, which is typically anIRI. This notion extends to the ability to identify graphs in the same manner. A developer may name data expressed using the@graphkeyword by pairing it with an@idkeyword. This enables the developer to make statements about alinked data graph itself, rather than just a singlesubject.

{  "@context": ...,"@id": "http://example.org/graphs/73",  "asOf": { "@value": "2012-04-09", "@type": "xsd:date" },  "@graph":  [    {      "@id": "http://manu.sporny.org/i/public",      "@type": "foaf:Person",      "name": "Manu Sporny",      "knows": "http://greggkellogg.net/foaf#me"    },    {      "@id": "http://greggkellogg.net/foaf#me",      "@type": "foaf:Person",      "name": "Gregg Kellogg",      "knows": "http://manu.sporny.org/i/public"    }  ]}

The example above expresses anamedlinked data graph that is identified by theIRIhttp://example.org/graphs/73. That graph is composed of the statements about Manu and Gregg. Meta-data about the graph itself is also expressed via theasOf property, which specifies when the information was retrieved from the Web.

4.11Identifying Unlabeled Nodes

At times, it becomes necessary to be able to express information withoutbeing able to specify the subject. Typically, this type of node is calledanunlabeled node or a blank node (see [RDF-CONCEPTS]Section 3.4: Blank Nodes).In JSON-LD,unlabeled node identifiers areautomatically created if a subject is not specified using the@idkeyword. However, authors may provide identifiers forunlabeled nodes by using the special_ (underscore)prefix. This allows one to reference the node locally within thedocument, but makes it impossible to reference the node from anexternal document. Theunlabeled node identifier is scoped to thedocument in which it is used.

{...  "@id": "_:foo",...}

The example above would set the subject to_:foo, which canthen be used elsewhere in the JSON-LD document to refer back to theunlabeled node. If a developer finds that they refer to the unlabelednode more than once, they should consider naming the node using a de-referenceableIRI so that it can be referenced also from other documents.

4.12Aliasing Keywords

Each of the JSON-LDkeywords,except for@context,may be aliased to application-specifickeywords. This feature allows legacy JSON content to be utilizedby JSON-LD by re-using JSON keys that already exist in legacy documents.This feature also allows developers to design domain-specific implementationsusing only the JSON-LDcontext.

{  "@context":  {"url": "@id","a": "@type",     "name": "http://schema.org/name"  },  "url": "http://example.com/about#gregg",  "a": "http://schema.org/Person",  "name": "Gregg Kellogg"}

In the example above, the@id and@typekeywords have been given the aliasesurl anda, respectively.

4.13Expanded Document Form

The JSON-LD API [JSON-LD-API] defines an method forexpanding a JSON-LD document. Expansion is the process of taking a JSON-LD document and applying a@context such that all IRIs, types, and values are expanded so that the@context is no longer necessary.

For example, assume the following JSON-LD input document:

{   "@context":   {      "name": "http://xmlns.com/foaf/0.1/name",      "homepage": {        "@id": "http://xmlns.com/foaf/0.1/homepage",        "@type", "@id"      }   },   "name": "Manu Sporny",   "homepage": "http://manu.sporny.org/"}

Running the JSON-LD Expansion algorithm against the JSON-LD input document provided above would result in the following output:

[  {    "http://xmlns.com/foaf/0.1/name": [      { "@value": "Manu Sporny" }    ],    "http://xmlns.com/foaf/0.1/homepage": [      { "@id": "http://manu.sporny.org/" }    ]  }]

Expanded document form is useful when an application has to process inputdata in a deterministic form. It has been optimized to ensure that the codethat developers have to write is minimized compared to the code that wouldhave to be written to operate oncompact document form.

4.14Compact Document Form

The JSON-LD API [JSON-LD-API] defines a method forcompacting a JSON-LD document. Compaction is the process of taking a JSON-LD document and applying a context such that the most compact form of the document is generated. JSON is typically expressed in a very compact, key-value format. That is, full IRIs are rarely used as keys. At times, a JSON-LD document may be received that is not in its most compact form. JSON-LD, via the API, provides a way to compact a JSON-LD document.

For example, assume the following JSON-LD input document:

[  {    "http://xmlns.com/foaf/0.1/name": [ "Manu Sporny" ],    "http://xmlns.com/foaf/0.1/homepage": [      {       "@id": "http://manu.sporny.org/"      }    ]  }]

Additionally, assume the following developer-supplied JSON-LD context:

{  "@context": {    "name": "http://xmlns.com/foaf/0.1/name",    "homepage": {      "@id": "http://xmlns.com/foaf/0.1/homepage",      "@type": "@id"    }  }}

Running the JSON-LD Compaction algorithm given the context supplied above against the JSON-LD input document provided above would result in the following output:

{  "@context": {    "name": "http://xmlns.com/foaf/0.1/name",    "homepage": {      "@id": "http://xmlns.com/foaf/0.1/homepage",      "@type": "@id"    }  },  "name": "Manu Sporny",  "homepage": "http://manu.sporny.org/"}

The compaction algorithm enables a developer to map any document into an application-specific compacted form by firstexpanding the document. While the context provided above mappedhttp://xmlns.com/foaf/0.1/name toname, it could have also mapped it to any arbitrary string provided by the developer. This powerful mechanism, along with another JSON-LD API technique calledframing, allows the developer to re-shape the incoming JSON data into a format that is optimized for their application.

The final details of the guidelines are still beingdiscussed (ISSUE-114),as well as the best mechanism to express these restrictions.EBNF doesn't quite capture what these guidelines are attempting to do -which is strongly express what constitutes a well-formed JSON-LD document.For the time being, a simple list of plain English guidelines are provided.

PerAndy S's comment, consider making this a normative syntax definition along with EBNF.

The intent of the Working Group and the Editors of this specification is toeventually align terminology used in this document with the terminology usedin the RDF Concepts document [RDF-CONCEPTS] to the extent to which it makes sense to do so.In general, if there is an analogue to terminology used in this document inthe RDF Concepts document, the preference is to use the terminology in theRDF Concepts document.

B.1RDF

This section is non-normative.

The RDF data model, as outlined in [RDF-CONCEPTS], is an abstract syntax for representing a directed graph of information. JSON-LD is capable of serializing any RDF graph, and performing full RDF to JSON-LD to RDF round-tripping. A complete description of how JSON-LD maps to RDF and algorithms detailing how one can convert from RDF to JSON-LD and from JSON-LD to RDF are included in the JSON-LD API [JSON-LD-API] specification.

B.2Turtle

The following are examples of convertingRDF expressed in [TURTLE-TR] into JSON-LD.

@prefix foaf: <http://xmlns.com/foaf/0.1/> .<http://manu.sporny.org/i/public> a foaf:Person;  foaf:name "Manu Sporny";  foaf:homepage <http://manu.sporny.org/> .

{  "@context":  {    "foaf": "http://xmlns.com/foaf/0.1/"  },  "@id": "http://manu.sporny.org/i/public",  "@type": "foaf:Person",  "foaf:name": "Manu Sporny",  "foaf:homepage": { "@id": "http://manu.sporny.org/" }}

{  "@context":  {"base": "http://manu.sporny.org/",    "foaf": "http://xmlns.com/foaf/0.1/"  },  "@id":"base:i/public",  "@type": "foaf:Person",  "foaf:name": "Manu Sporny",  "foaf:homepage": { "@id":"base"}}

@prefix foaf: <http://xmlns.com/foaf/0.1/> .<http://manu.sporny.org/i/public>  a foaf:Person;  foaf:name "Manu Sporny";  foaf:knows [ a foaf:Person; foaf:name "Gregg Kellogg" ] .

{  "@context":  {    "foaf": "http://xmlns.com/foaf/0.1/"  },  "@id": "http://manu.sporny.org/i/public",  "@type": "foaf:Person",  "foaf:name": "Manu Sporny",  "foaf:knows":  {    "@type": "foaf:Person",    "foaf:name": "Gregg Kellogg"  }}

@prefix foaf: <http://xmlns.com/foaf/0.1/> .<http://example.org/people#joebob> a foaf:Person;  foaf:name "Joe Bob";  foaf:nick ( "joe" "bob" "jaybee" ) .

{  "@context":  {    "foaf": "http://xmlns.com/foaf/0.1/"  },  "@id": "http://example.org/people#joebob",  "@type": "foaf:Person",  "foaf:name": "Joe Bob",  "foaf:nick":  {    "@list": [ "joe", "bob", "jaybee" ]  }}

B.3RDFa

The following example describes three people with their respective names andhomepages.

<divprefix="foaf: http://xmlns.com/foaf/0.1/">   <ul>      <litypeof="foaf:Person">        <arel="foaf:homepage" href="http://example.com/bob/" property="foaf:name">Bob</a>      </li>      <litypeof="foaf:Person">        <arel="foaf:homepage" href="http://example.com/eve/" property="foaf:name">Eve</a>      </li>      <litypeof="foaf:Person">        <arel="foaf:homepage" href="http://example.com/manu/" property="foaf:name">Manu</a>      </li>   </ul></div>

An example JSON-LD implementation using a singlecontext isdescribed below.

{  "@context":  {    "foaf": "http://xmlns.com/foaf/0.1/"  },  "@graph":  [    {      "@type": "foaf:Person",      "foaf:homepage": "http://example.com/bob/",      "foaf:name": "Bob"    },    {      "@type": "foaf:Person",      "foaf:homepage": "http://example.com/eve/",      "foaf:name": "Eve"    },    {      "@type": "foaf:Person",      "foaf:homepage": "http://example.com/manu/",      "foaf:name": "Manu"    }  ]}

B.4Microformats

The following example uses a simple Microformats hCard example to expresshow the Microformat is represented in JSON-LD.

<div class="vcard"> <a class="url fn" href="http://tantek.com/">Tantek Çelik</a></div>

The representation of the hCard expresses the Microformat terms in thecontext and uses them directly for theurl andfnproperties. Also note that the Microformat to JSON-LD processor hasgenerated the proper URL type forhttp://tantek.com/.

{  "@context":  {    "vcard": "http://microformats.org/profile/hcard#vcard",    "url":    {      "@id": "http://microformats.org/profile/hcard#url",      "@type": "@id"    },    "fn": "http://microformats.org/profile/hcard#fn"  },  "@type": "vcard",  "url": "http://tantek.com/",  "fn": "Tantek Çelik"}

B.5Microdata

The microdata example below expresses book information as a microdata Workitem.

<dl itemscope    itemtype="http://purl.org/vocab/frbr/core#Work"    itemid="http://purl.oreilly.com/works/45U8QJGZSQKDH8N"> <dt>Title</dt> <dd><cite itemprop="http://purl.org/dc/terms/title">Just a Geek</cite></dd> <dt>By</dt> <dd><span itemprop="http://purl.org/dc/terms/creator">Wil Wheaton</span></dd> <dt>Format</dt> <dd itemprop="http://purl.org/vocab/frbr/core#realization"     itemscope     itemtype="http://purl.org/vocab/frbr/core#Expression"     itemid="http://purl.oreilly.com/products/9780596007683.BOOK">  <link itemprop="http://purl.org/dc/terms/type" href="http://purl.oreilly.com/product-types/BOOK">  Print </dd> <dd itemprop="http://purl.org/vocab/frbr/core#realization"     itemscope     itemtype="http://purl.org/vocab/frbr/core#Expression"     itemid="http://purl.oreilly.com/products/9780596802189.EBOOK">  <link itemprop="http://purl.org/dc/terms/type" href="http://purl.oreilly.com/product-types/EBOOK">  Ebook </dd></dl>

Note that the JSON-LD representation of the Microdata information staystrue to the desires of the Microdata community to avoid contexts andinstead refer to items by their fullIRI.

[  {    "@id": "http://purl.oreilly.com/works/45U8QJGZSQKDH8N",    "@type": "http://purl.org/vocab/frbr/core#Work",    "http://purl.org/dc/terms/title": "Just a Geek",    "http://purl.org/dc/terms/creator": "Whil Wheaton",    "http://purl.org/vocab/frbr/core#realization":    [      "http://purl.oreilly.com/products/9780596007683.BOOK",      "http://purl.oreilly.com/products/9780596802189.EBOOK"    ]  },  {    "@id": "http://purl.oreilly.com/products/9780596007683.BOOK",    "@type": "http://purl.org/vocab/frbr/core#Expression",    "http://purl.org/dc/terms/type": "http://purl.oreilly.com/product-types/BOOK"  },  {    "@id": "http://purl.oreilly.com/products/9780596802189.EBOOK",    "@type": "http://purl.org/vocab/frbr/core#Expression",    "http://purl.org/dc/terms/type": "http://purl.oreilly.com/product-types/EBOOK"  }]

E.1Normative references

[BCP47]

A. Phillips; M. Davis.Tags for Identifying Languages September 2009. IETF Best Current Practice. URL:http://tools.ietf.org/html/bcp47

[JSON-LD-API]

The JSON-LD API 1.0 Manu Sporny, Gregg Kellogg, Dave Longley, Markus Lanthaler, Editors. World Wide Web Consortium (work in progress). 24 May 2012. Editor's Draft. This edition of the JSON-LD Syntax specification is http://json-ld.org/spec/ED/json-ld-api/20120524/. Thelatest edition of the JSON-LD Syntax is available at http://json-ld.org/spec/latest/json-ld-api/

[RDF-CONCEPTS]

RDF 1.1 Concepts and Abstract Syntax Richard Cyganiak, David Wood, Editors. World Wide Web Consortium (work in progress). 30 May 2012. Editor's Draft. This edition of the JSON-LD Syntax specification is http://www.w3.org/TR/2011/WD-rdf11-concepts-20110830/. Thelatest edition of the JSON-LD Syntax is available at http://www.w3.org/TR/rdf11-concepts/

[RFC3987]

M. Dürst; M. Suignard.Internationalized Resource Identifiers (IRIs). January 2005. Internet RFC 3987. URL:http://www.ietf.org/rfc/rfc3987.txt

[RFC4627]

D. Crockford.The application/json Media Type for JavaScript Object Notation (JSON) July 2006. Internet RFC 4627. URL:http://www.ietf.org/rfc/rfc4627.txt

[RFC5988]

Web Linking M. Nottingham. Editor. October 2010. IETF Standard. URL:http://tools.ietf.org/rfc/rfc5988.txt

E.2Informative references

[RDF-PRIMER]

Frank Manola; Eric Miller.RDF Primer. 10 February 2004. W3C Recommendation. URL:http://www.w3.org/TR/2004/REC-rdf-primer-20040210/

[RDFA-CORE]

Shane McCarron; et al.RDFa Core 1.1: Syntax and processing rules for embedding RDF through attributes. 7 June 2012. W3C Recommendation. URL:http://www.w3.org/TR/2012/REC-rdfa-core-20120607/

[TURTLE-TR]

Eric Prud'hommeaux, Gavin Carothers.Turtle: Terse RDF Triple Language. 09 August 2011. W3C Working Draft. URL:http://www.w3.org/TR/2011/WD-turtle-20110809/