+ Basic Concepts
+
+ JSON [[RFC7159]] is a lightweight, language-independent data interchange format.
+ It is easy to parse and easy to generate. However, it is difficult to integrate JSON
+ from different sources as the data may contain keys that conflict with other
+ data sources. Furthermore, JSON has no
+ built-in support for hyperlinks, which are a fundamental building block on
+ the Web. Let's start by looking at an example that we will be using for the
+ rest of this section:
+
+
+
+
+
+ It's obvious to humans that the data is about a person whose
+ name is "Manu Sporny"
+ and that the homepage property contains the URL of that person's homepage.
+ A machine doesn't have such an intuitive understanding and sometimes,
+ even for humans, it is difficult to resolve ambiguities in such representations. This problem
+ can be solved by using unambiguous identifiers to denote the different concepts instead of
+ tokens such as "name", "homepage", etc.
+
+ Linked Data, and the Web in general, uses IRIs
+ (Internationalized Resource Identifiers as described in [[!RFC3987]]) for unambiguous
+ identification. The idea is to use IRIs
+ to assign unambiguous identifiers to data that may be of use to other developers.
+ It is useful for terms,
+ like name and homepage, to expand to IRIs
+ so that developers don't accidentally step on each other's terms. Furthermore, developers and
+ machines are able to use this IRI (by using a web browser, for instance) to go to
+ the term and get a definition of what the term means. This process is known as IRI
+ dereferencing.
+
+ Leveraging the popular schema.org vocabulary,
+ the example above could be unambiguously expressed as follows:
+
+
+
+
+
+ In the example above, every property is unambiguously identified by an IRI and all values
+ representing IRIs are explicitly marked as such by the
+ @id keyword. While this is a valid JSON-LD
+ document that is very specific about its data, the document is also overly verbose and difficult
+ to work with for human developers. To address this issue, JSON-LD introduces the notion
+ of a context as described in the next section.
+
+
+ The Context
+
+ When two people communicate with one another, the conversation takes
+ place in a shared environment, typically called
+ "the context of the conversation". This shared context allows the
+ individuals to use shortcut terms, like the first name of a mutual friend,
+ to communicate more quickly but without losing accuracy. A context in
+ JSON-LD works in the same way. It allows two applications to use shortcut
+ terms to communicate with one another more efficiently, but without
+ losing accuracy.
+
+ Simply speaking, a context is used to map terms to
+ IRIs. Terms are case sensitive
+ and any valid string that is not a reserved JSON-LD keyword
+ can be used as a term.
+
+ For the sample document in the previous section, a context would
+ look something like this:
+
+
+
+
+
+ As the context above shows, the value of a term definition can
+ either be a simple string, mapping the term to an IRI,
+ or a JSON object.
+
+ When a JSON object is associated with a term, it is called
+ an expanded term definition. The example above specifies that
+ the values of image and homepage, if they are
+ strings, are to be interpreted as
+ IRIs. Expanded term definitions
+ also allow terms to be used for index maps
+ and to specify whether array values are to be
+ interpreted as sets or lists.
+ Expanded term definitions may
+ be defined using absolute or
+ compact IRIs as keys, which is
+ mainly used to associate type or language information with an
+ absolute or compact IRI.
+
+ Contexts can either be directly embedded
+ into the document or be referenced. Assuming the context document in the previous
+ example can be retrieved at https://json-ld.org/contexts/person.jsonld,
+ it can be referenced by adding a single line and allows a JSON-LD document to
+ be expressed much more concisely as shown in the example below:
+
+
+
+
+
+ The referenced context not only specifies how the terms map to
+ IRIs in the Schema.org vocabulary but also
+ specifies that string values associated with
+ the homepage and image property
+ can be interpreted as an IRI ("@type": "@id",
+ see for more details). This information allows developers
+ to re-use each other's data without having to agree to how their data will interoperate
+ on a site-by-site basis. External JSON-LD context documents may contain extra
+ information located outside of the @context key, such as
+ documentation about the terms declared in the
+ document. Information contained outside of the @context value
+ is ignored when the document is used as an external JSON-LD context document.
+
+ JSON documents can be interpreted as JSON-LD without having to be modified by
+ referencing a context via an HTTP Link Header
+ as described in . It is also
+ possible to apply a custom context using the JSON-LD 1.1 API [[JSON-LD11-API]].
+
+ In JSON-LD documents,
+ contexts may also be specified inline.
+ This has the advantage that documents can be processed even in the
+ absence of a connection to the Web. Ultimately, this is a modeling decision
+ and different use cases may require different handling.
+
+
+
+
+
+ This section only covers the most basic features of the JSON-LD
+ Context. More advanced features related to the JSON-LD Context are covered
+ in section .
+
+
+
+
+ IRIs
+
+ IRIs (Internationalized Resource Identifiers
+ [[!RFC3987]]) are fundamental to Linked Data as that is how most
+ nodes and properties
+ are identified. In JSON-LD, IRIs may be represented as an
+ absolute IRI or a relative IRI. An
+ absolute IRI is defined in [[!RFC3987]] as containing a
+ scheme along with path and optional query and
+ fragment segments. A relative IRI is an IRI
+ that is relative to some other absolute IRI.
+ In JSON-LD, with exceptions are as described below, all relative IRIs
+ are resolved relative to the base IRI.
+
+ Properties, values of @type,
+ and values of properties with a term definition
+ that defines them as being relative to the vocabulary mapping,
+ may have the form of a relative IRI, but are resolved using the
+ vocabulary mapping, and not the base IRI.
+
+ A string is interpreted as an IRI when it is the
+ value of an @id member:
+
+
+
+
+
+ Values that are interpreted as IRIs, can also be
+ expressed as relative IRIs. For example,
+ assuming that the following document is located at
+ http://example.com/about/, the relative IRI
+ ../ would expand to http://example.com/ (for more
+ information on where relative IRIs can be
+ used, please refer to section ).
+
+
+
+
+
+ Absolute IRIs can be expressed directly
+ in the key position like so:
+
+
+
+
+
+ In the example above, the key http://schema.org/name
+ is interpreted as an absolute IRI.
+
+ Term-to-IRI expansion occurs if the key matches a term defined
+ within the active context:
+
+
+
+
+
+ JSON keys that do not expand to an IRI, such as status
+ in the example above, are not Linked Data and thus ignored when processed.
+
+ If type coercion rules are specified in the @context for
+ a particular term or property IRI, an IRI is generated:
+
+
+
+
+
+ In the example above, since the value http://manu.sporny.org/
+ is expressed as a JSON string, the type coercion
+ rules will transform the value into an IRI when processing the data.
+ See for more
+ details about this feature.
+
+ In summary, IRIs can be expressed in a variety of
+ different ways in JSON-LD:
+
+
+ - JSON object keys that have a term mapping in
+ the active context expand to an IRI
+ (only applies outside of the context definition).
+ - An IRI is generated for the string value specified using
+
@id or @type.
+ - An IRI is generated for the string value of any key for which there
+ are coercion rules that contain an
@type key that is
+ set to a value of @id or @vocab.
+
+
+ This section only covers the most basic features associated with IRIs
+ in JSON-LD. More advanced features related to IRIs are covered in
+ section .
+
+
+
+
+
+
+
+
+
+
+Advanced Concepts
+
+JSON-LD has a number of features that provide functionality above and beyond
+ the core functionality described above. The following section describes this
+ advanced functionality in more detail.
+
+
+
+
+
+
+
+
+ Compact IRIs
+
+ A compact IRI is a way of expressing an IRI
+ using a prefix and suffix separated by a colon (:).
+ The prefix is a term taken from the
+ active context and is a short string identifying a
+ particular IRI in a JSON-LD document. For example, the
+ prefix foaf may be used as a short hand for the
+ Friend-of-a-Friend vocabulary, which is identified using the IRI
+ http://xmlns.com/foaf/0.1/. A developer may append
+ any of the FOAF vocabulary terms to the end of the prefix to specify a short-hand
+ version of the absolute IRI for the vocabulary term. For example,
+ foaf:name would be expanded to the IRI
+ http://xmlns.com/foaf/0.1/name.
+
+
+
+
+
+ In the example above, foaf:name expands to the IRI
+ http://xmlns.com/foaf/0.1/name and foaf:Person expands
+ to http://xmlns.com/foaf/0.1/Person.
+
+ Prefixes are expanded when the form of the value
+ is a compact IRI represented as a prefix:suffix
+ combination, the prefix matches a term defined within the
+ active context, and the suffix does not begin with two
+ slashes (//). The compact IRI is expanded by
+ concatenating the IRI mapped to the prefix to the (possibly empty)
+ suffix. If the prefix is not defined in the active context,
+ or the suffix begins with two slashes (such as in http://example.com),
+ the value is interpreted as absolute IRI instead. If the prefix is an
+ underscore (_), the value is interpreted as blank node identifier
+ instead.
+
+ It's also possible to use compact IRIs within the context as shown in the
+ following example:
+
+
+
+
+
+ In JSON-LD 1.0, terms may be chosen as compact IRI prefixes when
+ compacting only if a simple term definition is used where the value ends with a
+ URI gen-delim character (e.g, /,
+ # and others, see [[!RFC3986]]).
+ The previous specification allows any term to be chosen as
+ a compact IRI prefix, which led to a poor experience.
+
+ In JSON-LD 1.1, terms may be chosen as compact IRI prefixes
+ when compacting only if
+ a simple term definition is used where the value ends with a URI gen-delim character,
+ or if their expanded term definition contains
+ a @prefix member with the value true.
+
+ This represents a small change to the 1.0 algorithm to prevent IRIs
+ that are not really intended to be used as prefixes from being used for creating
+ compact IRIs.
+
+ When processing mode is set to json-ld-1.1, terms will be used as compact IRI prefixes
+ when compacting only if their expanded term definition contains
+ a @prefix member with the value true, or if it has a
+ a simple term definition where the value ends with a URI gen-delim character
+ (e.g, /, # and others, see [[!RFC3986]]).
+
+
+
+
+
+ In this case, the compact-iris term would not normally be usable as a prefix, both
+ because it is defined with an expanded term definition, and because
+ it's @id does not end in a
+ gen-delim character. Adding
+ "@prefix": true allows it to be used as the prefix portion of
+ the compact IRI compact-iris:are-considered.
+
+
+
+
+
+
+
+
+
+
+
+ Interpreting JSON as JSON-LD
+
+ Ordinary JSON documents can be interpreted as JSON-LD
+ by providing an explicit JSON-LD context document. One way
+ to provide this is by using referencing a JSON-LD
+ context document in an HTTP Link Header.
+ Doing so allows JSON to be unambiguously machine-readable without requiring developers to drastically
+ change their documents and provides an upgrade path for existing infrastructure
+ without breaking existing clients that rely on the application/json
+ media type or a media type with a +json suffix as defined in
+ [[RFC6839]].
+
+ In order to use an external context with an ordinary JSON document,
+ when retrieving an ordinary JSON document via HTTP, processors MUST
+ retrieve any JSON-LD document referenced by a
+ Link Header with:
+
+
+ rel="http://www.w3.org/ns/json-ld#context", andtype="application/ld+json".
+
+ The referenced document MUST have a top-level JSON object.
+ The @context subtree within that object is added to the top-level
+ JSON object of the referencing document. If an array
+ is at the top-level of the referencing document and its items are
+ JSON objects, the @context
+ subtree is added to all array items. All extra information located outside
+ of the @context subtree in the referenced document MUST be
+ discarded. Effectively this means that the active context is
+ initialized with the referenced external context. A response MUST NOT
+ contain more than one HTTP Link Header [[!RFC5988]] using the
+ http://www.w3.org/ns/json-ld#context link relation.
+
+ Other mechanisms for providing a JSON-LD Context MAY be described for other
+ URI schemes.
+
+ The JSON-LD 1.1 Processing Algorithms and API specification [[JSON-LD11-API]]
+ provides for an expandContext option for specifying
+ a context to use when expanding JSON documents programatically.
+
+ The following example demonstrates the use of an external context with an
+ ordinary JSON document over HTTP:
+
+
+
+
+
+ Please note that JSON-LD documents
+ served with the application/ld+json
+ media type MUST have all context information, including references to external
+ contexts, within the body of the document. Contexts linked via a
+ http://www.w3.org/ns/json-ld#context HTTP Link Header MUST be
+ ignored for such documents.
+
+
+
+ String Internationalization
+
+ At times, it is important to annotate a string
+ with its language. In JSON-LD this is possible in a variety of ways.
+ First, it is possible to define a default language for a JSON-LD document
+ by setting the @language key in the context:
+
+
+
+
+
+ The example above would associate the ja language
+ code with the two strings 花澄 and 科学者.
+ Languages codes are defined in [[!BCP47]]. The default language applies to all
+ string values that are not type coerced.
+
+ To clear the default language for a subtree, @language can
+ be set to null in a local context as follows:
+
+
+
+
+
+ Second, it is possible to associate a language with a specific term
+ using an expanded term definition:
+
+
+
+
+
+ The example above would associate 忍者 with the specified default
+ language code ja, Ninja with the language code
+ en, and Nindža with the language code cs.
+ The value of name, Yagyū Muneyoshi wouldn't be
+ associated with any language code since @language was reset to
+ null in the expanded term definition.
+
+ Language associations are only applied to plain
+ strings. Typed values
+ or values that are subject to type coercion
+ are not language tagged.
+
+ Just as in the example above, systems often need to express the value of a
+ property in multiple languages. Typically, such systems also try to ensure that
+ developers have a programmatically easy way to navigate the data structures for
+ the language-specific data. In this case, language maps
+ may be utilized.
+
+
+
+
+
+ The example above expresses exactly the same information as the previous
+ example but consolidates all values in a single property. To access the
+ value in a specific language in a programming language supporting dot-notation
+ accessors for object properties, a developer may use the
+ property.language pattern. For example, to access the occupation
+ in English, a developer would use the following code snippet:
+ obj.occupation.en.
+
+ Third, it is possible to override the default language by using a
+ value object:
+
+
+
+
+
+ This makes it possible to specify a plain string by omitting the
+ @language tag or setting it to null when expressing
+ it using a value object:
+
+
+
+
+
+
+
+
+
+
+Sets and Lists
+
+A JSON-LD author can express multiple values in a compact way by using
+ arrays. Since graphs do not describe ordering for links
+ between nodes, arrays in JSON-LD do not provide an ordering of the
+ contained elements by default. This is exactly the opposite from regular JSON
+ arrays, which are ordered by default. For example, consider the following
+ simple document:
+
+
+
+
+
+The example shown above would result in the following data being generated,
+ each relating the node to an individual value, with no inherent order:
+
+
+
+ | Subject |
+ Property |
+ Value |
+
+
+
+ | http://example.org/people#joebob |
+ foaf:nick |
+ joe |
+
+
+ | http://example.org/people#joebob |
+ foaf:nick |
+ bob |
+
+
+ | http://example.org/people#joebob |
+ foaf:nick |
+ JB |
+
+
+
+
+Multiple values may also be expressed using the expanded form:
+
+
+
+
+
+The example shown above would generate the following data, again with
+ no inherent order:
+
+
+
+ | Subject |
+ Property |
+ Value |
+ Language |
+
+
+
+ | http://example.org/articles/8 |
+ dc:title |
+ Das Kapital |
+ de |
+
+
+ | http://example.org/articles/8 |
+ dc:title |
+ Capital |
+ en |
+
+
+
+
+Although multiple values of a property are typically of the same type,
+ JSON-LD places no restriction on this, and a property may have values
+ of different types:
+
+
+
+
+
+The example shown above would generate the following data, also with
+ no inherent order:
+
+
+
+ | Subject |
+ Property |
+ Value |
+ Language |
+ Value Type |
+
+
+
+ | http://example.org/people#michael |
+ dc:name |
+ Michael |
+ |
+ |
+
+
+ | http://example.org/people#michael |
+ dc:name |
+ Mike |
+ |
+ |
+
+
+ | http://example.org/people#michael |
+ dc:name |
+ Miguel |
+ es |
+ |
+
+
+ | http://example.org/people#michael |
+ dc:name |
+ https://www.wikidata.org/wiki/Q4927524 |
+ |
+ |
+
+
+ | http://example.org/people#michael |
+ dc:name |
+ 42 |
+ |
+ xsd:integer |
+
+
+
+
+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 @list keyword as follows:
+
+
+
+
+This describes the use of this array 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 the context:
+
+
+
+
+List of lists in the form of list objects
+ are not allowed in this version of JSON-LD. This decision was made due to the
+ extreme amount of added complexity when processing lists of lists.
+
+While @list is used to describe ordered lists,
+ the @set keyword is used to describe unordered sets.
+ The use of @set in the body of a JSON-LD document
+ is optimized away when processing the document, as it is just syntactic
+ sugar. However, @set is helpful when used within the context
+ of a document.
+ Values of terms associated with an @set or @list container
+ are always represented in the form of an array,
+ even if there is just a single value that would otherwise be optimized to
+ a non-array form in compact form (see
+ ). This makes post-processing of
+ JSON-LD documents easier as the data is always in array form, even if the
+ array only contains a single value.
+
+
+
+
+
+
+ Scoped Contexts
+
+ An expanded term definition can include a @context
+ property, which defines a context (an embedded context) for values of properties defined using that term. This allows
+ values to use term definitions, base IRI,
+ vocabulary mapping or default language which is different from the
+ node object they are contained in, as if the
+ context was specified within the value itself.
+
+
+
+
+
+ In this case, the social profile is defined using the schema.org vocabulary, but interest is imported from FOAF, and is used to define a node describing one of Manu's interests where those properties now come from the FOAF vocabulary.
+
+ Expanding this document, uses a combination of terms defined in the outer context, and those defined specifically for that term in an embedded context.
+
+
+
+
+
+ Scoping can also be performed using a term used as a value of @type:
+
+
+
+
+
+ Scoping on @type is useful when common properties are used to
+ relate things of different types, where the vocabularies in use within
+ different entities calls for different context scoping. For example,
+ hasPart/partOf may be common terms used in a document, but mean
+ different things depending on the context.
+
+ When expanding, each value of @type is considered
+ (ordering them lexographically) where that value is also a term in
+ the active context having its own embedded context. If so, that
+ embedded context is applied to the active context. When compacting, if
+ a term is chosen to represent an IRI used as a value of @type where that
+ term definition also has an embedded context, it is then applied to the
+ active context to affect further compaction.
+
+ The values of @type are unordered, so if multiple
+ types are listed, the order that scoped contexts are applied is based on
+ lexicographical ordering.
+
+ If a term defines a scoped context, and then that term
+ is later re-defined, the association of the context defined in the earlier
+ expanded term definition is lost
+ within the scope of that re-definition. This is consistent with
+ term definitions of a term overriding previous term definitions from
+ earlier less deeply nested definitions, as discussed in
+ .
+
+ Scoped Contexts are a new feature in JSON-LD 1.1, requiring
+ processing mode set to json-ld-1.1.
+
+
+
+
+
+
+
+
+
+
+
+ Named Graph Indexing
+
+ In addition to indexing node objects by index, graph objects may
+ also be indexed by an index. By using the @graph
+ container type, introduced in
+ in addition to @index, an object value of such a property is
+ treated as a key-value map where the keys do not map to IRIs, but
+ are taken from an @index property associated with named graphs
+ which are their values. When expanded, these must be simple graph objects
+
+ The following example describes a default graph referencing multiple named
+ graphs using an index map.
+
+
+
+
+
+ This expands to the following:
+
+
+
+
+
+ When expressed as Quads, this becomes the following:
+
+
+
+ | Graph |
+ Subject |
+ Property |
+ Value |
+ Value Type |
+
+
+
+ | |
+ http://example.com/ |
+ rdf:type |
+ schema:Blog |
+ |
+
+
+ | |
+ http://example.com/ |
+ schema:name |
+ World Financial News |
+ |
+
+
+ | |
+ http://example.com/ |
+ schema:blogPost |
+ _:b1 |
+ |
+
+
+ | |
+ http://example.com/ |
+ schema:blogPost |
+ _:b2 |
+ |
+
+
+ | _:b1 |
+ http://example.com/posts/1/de |
+ schema:wordCount |
+ 1204 |
+ xsd:integer |
+
+
+ | _:b1 |
+ http://example.com/posts/1/de |
+ schema:articleBody |
+ Die Werte an Warenbörsen stiegen im Sog eines starken Handels von Rohöl... |
+ |
+
+
+ | _:b2 |
+ http://example.com/posts/1/en |
+ schema:wordCount |
+ 1539 |
+ xsd:integer |
+
+
+ | _:b2 |
+ http://example.com/posts/1/en |
+ schema:articleBody |
+ World commodities were up today with heavy trading of crude oil... |
+ |
+
+
+
+
+ As with index maps, when used with @graph, a container may also
+ include @set to ensure that key values are always contained in an array.
+
+ If the processing mode is set to json-ld-1.1,
+ the special index @none is used for indexing
+ graphs which does not have an @index key, which is useful to maintain
+ a normalized representation. Note, however, that
+ compacting a document where multiple unidentified named graphs are
+ compacted using the @none index will result in the content
+ of those graphs being merged. To prevent this, give each graph a distinct
+ @index key.
+
+
+
+
+
+ This expands to the following:
+
+
+
+
+
+
+
+
+
+
+
+ Named Graph Indexing by Identifier
+
+ In addition to indexing node objects by identifier, graph objects may
+ also be indexed by their graph name. By using the @graph
+ container type, introduced in
+ in addition to @id, an object value of such a property is
+ treated as a key-value map where the keys represent the identifiers of named graphs
+ which are their values.
+
+ The following example describes a default graph referencing multiple named
+ graphs using an id map.
+
+
+
+
+
+ This expands to the following:
+
+
+
+
+
+ When expressed as Quads, this becomes the following:
+
+
+
+ | Graph |
+ Subject |
+ Property |
+ Value |
+ Value Type |
+
+
+
+ | |
+ _:graph |
+ prov:generatedAtTime |
+ 2012-04-09 |
+ xsd:date |
+
+
+ | |
+ _:graph |
+ http://example.org/graphMap |
+ http://manu.sporny.org/about#manu |
+ |
+
+
+ | |
+ _:graph |
+ http://example.org/graphMap |
+ http://greggkellogg.net/foaf#me |
+ |
+
+
+ | _:manu |
+ http://manu.sporny.org/about#manu |
+ xsd:type |
+ foaf:Person |
+ |
+
+
+ | _:manu |
+ http://manu.sporny.org/about#manu |
+ foaf:name |
+ Manu Sporny |
+ |
+
+
+ | _:manu |
+ http://manu.sporny.org/about#manu |
+ foaf:knows |
+ http://greggkellogg.net/foaf#me |
+ |
+
+
+ | _:gregg |
+ http://greggkellogg.net/foaf#me |
+ xsd:type |
+ foaf:Person |
+ |
+
+
+ | _:gregg |
+ http://greggkellogg.net/foaf#me |
+ foaf:name |
+ Gregg Kellogg |
+ |
+
+
+ | _:gregg |
+ http://greggkellogg.net/foaf#me |
+ foaf:knows |
+ http://manu.sporny.org/about#manu |
+ |
+
+
+
+
+ As with id maps, when used with @graph, a container may also
+ include @set to ensure that key values are always contained in an array.
+
+ As with id maps, the special index @none is used for indexing
+ named graphs which do not have an @id, which is useful to maintain
+ a normalized representation. The @none index may also be
+ a term which expands to @none.
+ Note, however, that if multiple graphs are represented without
+ an @id, they will be merged on expansion. To prevent this,
+ use @none judiciously, and consider giving graphs
+ their own distinct identifier.
+
+
+
+
+
+ Graph Containers are a new feature in JSON-LD 1.1, requiring
+ processing mode set to json-ld-1.1.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ JSON-LD Grammar
+
+ This appendix restates the syntactic conventions described in the
+ previous sections more formally.
+
+ A JSON-LD document MUST be valid JSON text as described
+ in [[!RFC7159]], or some format that can be represented
+ in the JSON-LD internal representation that is equivalent to
+ valid JSON text.
+
+ A JSON-LD document MUST be a single node object,
+ a JSON object consisting of only
+ the members @context and/or @graph,
+ or an array or zero or more node objects.
+
+ In contrast to JSON, in JSON-LD the keys in objects
+ MUST be unique.
+
+ JSON-LD allows keywords to be aliased
+ (see for details). Whenever a keyword is
+ discussed in this grammar, the statements also apply to an alias for
+ that keyword. For example, if the active context
+ defines the term id as an alias for @id,
+ that alias may be legitimately used as a substitution for @id.
+ Note that keyword aliases are not expanded during context
+ processing.
+
+
+ Terms
+
+ A term is a short-hand string that expands
+ to an IRI or a blank node identifier.
+
+ A term MUST NOT equal any of the JSON-LD
+ keywords.
+
+ When used as the prefix in a Compact IRI, to avoid
+ the potential ambiguity of a prefix being confused with an IRI
+ scheme, terms SHOULD NOT come from the list of URI schemes as defined in
+ [[!IANA-URI-SCHEMES]]. Similarly, to avoid confusion between a
+ Compact IRI and a term, terms SHOULD NOT include a colon (:)
+ and SHOULD be restricted to the form of
+ isegment-nz-nc
+ as defined in [[!RFC3987]].
+
+ To avoid forward-compatibility issues, a term SHOULD NOT start
+ with an @ character as future versions of JSON-LD may introduce
+ additional keywords. Furthermore, the term MUST NOT
+ be an empty string ("") as not all programming languages
+ are able to handle empty JSON keys.
+
+ See and
+ for further discussion
+ on mapping terms to IRIs.
+
+
+
+ Node Objects
+
+ A node object represents zero or more properties of a
+ node in the graph serialized by the
+ JSON-LD document. A JSON object is a
+ node object if it exists outside of a JSON-LD
+ context and:
+
+
+ - it is not the top-most JSON object in the JSON-LD document consisting
+ of no other members than
@graph and @context,
+ - it does not contain the
@value, @list,
+ or @set keywords, and
+ - it is not a graph object.
+
+
+ The properties of a node in
+ a graph may be spread among different
+ node objects within a document. When
+ that happens, the keys of the different
+ node objects need to be merged to create the
+ properties of the resulting node.
+
+ A node object MUST be a JSON object. All keys
+ which are not IRIs, compact IRIs, terms valid in the
+ active context, or one of the following keywords
+ (or alias of such a keyword)
+ MUST be ignored when processed:
+
+
+ @context,@id,@graph,@nest,@type,@reverse, or@index
+
+ If the node object contains the @context
+ key, its value MUST be null, an absolute IRI,
+ a relative IRI, a context definition, or
+ an array composed of any of these.
+
+ If the node object contains the @id key,
+ its value MUST be an absolute IRI, a relative IRI,
+ or a compact IRI (including
+ blank node identifiers).
+ See ,
+ , and
+ for further discussion on
+ @id values.
+
+ If the node object contains the @graph
+ key, its value MUST be
+ a node object or
+ an array of zero or more node objects.
+ If the node object contains an @id keyword,
+ its value is used as the graph name of a named graph.
+ See for further discussion on
+ @graph values. As a special case, if a JSON object
+ contains no keys other than @graph and @context, and the
+ JSON object is the root of the JSON-LD document, the
+ JSON object is not treated as a node object; this
+ is used as a way of defining node objects
+ that may not form a connected graph. This allows a
+ context to be defined which is shared by all of the constituent
+ node objects.
+
+ If the node object contains the @type
+ key, its value MUST be either an absolute IRI, a
+ relative IRI, a compact IRI
+ (including blank node identifiers),
+ a term defined in the active context expanding into an absolute IRI, or
+ an array of any of these.
+ See for further discussion on
+ @type values.
+
+ If the node object contains the @reverse key,
+ its value MUST be a JSON object containing members representing reverse
+ properties. Each value of such a reverse property MUST be an absolute IRI,
+ a relative IRI, a compact IRI, a blank node identifier,
+ a node object or an array containing a combination of these.
+
+ If the node object contains the @index key,
+ its value MUST be a string. See
+ for further discussion
+ on @index values.
+
+ If the node object contains the @nest key,
+ its value MUST be an JSON object or an array of JSON objects
+ which MUST NOT include a value object. See
+ for further discussion
+ on @nest values.
+
+ Keys in a node object that are not
+ keywords MAY expand to an absolute IRI
+ using the active context. The values associated with keys that expand
+ to an absolute IRI MUST be one of the following:
+
+
+ - string,
+ - number,
+ - true,
+ - false,
+ - null,
+ - node object,
+ - graph object,
+ - value object,
+ - list object,
+ - set object,
+ - an array of zero or more of any of the possibilities above,
+ - a language map,
+ - an index map,
+ - an id map, or
+ - an type map
+
+
+
+
+ Graph Objects
+
+ A graph object represents a named graph, which MAY include
+ include an explicit graph name.
+ A JSON object is a graph object if
+ it exists outside of a JSON-LD context,
+ it is not a node object,
+ it is not the top-most JSON object in the JSON-LD document, and
+ it consists of no members other than @graph,
+ @index, @id
+ and @context, or an alias of one of these keywords.
+
+ If the graph object contains the @context
+ key, its value MUST be null, an absolute IRI,
+ a relative IRI, a context definition, or
+ an array composed of any of these.
+
+ If the graph object contains the @id key,
+ its value is used as the identifier (graph name) of a named graph, and
+ MUST be an absolute IRI, a relative IRI,
+ or a compact IRI (including
+ blank node identifiers).
+ See ,
+ , and
+ for further discussion on
+ @id values.
+
+ A graph object without an @id member is also a
+ simple graph object and represents a named graph without an
+ explicit identifier, although in the data model it still has a
+ graph name, which is an implicitly allocated
+ blank node identifier.
+
+ The value of the @graph key MUST be
+ a node object or
+ an array of zero or more node objects.
+ See for further discussion on
+ @graph values..
+
+
+
+ Value Objects
+
+ A value object is used to explicitly associate a type or a
+ language with a value to create a typed value or a language-tagged
+ string.
+
+ A value object MUST be a JSON object containing the
+ @value key. It MAY also contain an @type,
+ an @language, an @index, or an @context key but MUST NOT contain
+ both an @type and an @language key at the same time.
+ A value object MUST NOT contain any other keys that expand to an
+ absolute IRI or keyword.
+
+ The value associated with the @value key MUST be either a
+ string, a number, true,
+ false or null.
+
+ The value associated with the @type key MUST be a
+ term, a compact IRI,
+ an absolute IRI, a string which can be turned
+ into an absolute IRI using the vocabulary mapping, or null.
+
+ The value associated with the @language key MUST have the
+ lexical form described in [[!BCP47]], or be null.
+
+ The value associated with the @index key MUST be a
+ string.
+
+ See and
+
+ for more information on value objects.
+
+
+
+ Lists and Sets
+
+ A list represents an ordered set of values. A set
+ represents an unordered set of values. Unless otherwise specified,
+ arrays are unordered in JSON-LD. As such, the
+ @set keyword, when used in the body of a JSON-LD document,
+ represents just syntactic sugar which is optimized away when processing the document.
+ However, it is very helpful when used within the context of a document. Values
+ of terms associated with an @set or @list container
+ will always be represented in the form of an array when a document
+ is processed—even if there is just a single value that would otherwise be optimized to
+ a non-array form in compact document form.
+ This simplifies post-processing of the data as the data is always in a
+ deterministic form.
+
+ A list object MUST be a JSON object that contains no
+ keys that expand to an absolute IRI or keyword other
+ than @list, @context, and @index.
+
+ A set object MUST be a JSON object that contains no
+ keys that expand to an absolute IRI or keyword other
+ than @set, @context, and @index.
+ Please note that the @index key will be ignored when being processed.
+
+ In both cases, the value associated with the keys @list and @set
+ MUST be one of the following types:
+
+
+ See for further discussion on sets and lists.
+
+
+
+ Language Maps
+
+ A language map is used to associate a language with a value in a
+ way that allows easy programmatic access. A language map may be
+ used as a term value within a node object if the term is defined
+ with @container set to @language,
+
+ or an array containing both @language and @set
+ . The keys of a
+ language map MUST be strings representing
+ [[BCP47]] language codes, the keyword @none,
+ or a term which expands to @none,
+ and the values MUST be any of the following types:
+
+
+
+ See for further discussion
+ on language maps.
+
+
+
+ Index Maps
+
+ An index map allows keys that have no semantic meaning,
+ but should be preserved regardless, to be used in JSON-LD documents.
+ An index map may
+ be used as a term value within a node object if the
+ term is defined with @container set to @index,
+
+ or an array containing both @index and @set
+ .
+ The values of the members of an index map MUST be one
+ of the following types:
+
+
+
+ See for further information on this topic.
+
+ Index Maps may also be used to map indexes to associated
+ named graphs, if the term is defined with @container
+ set to an array containing both @graph and
+ @index, and optionally including @set. The
+ value consists of the node objects contained within the named
+ graph which is named using the referencing key, which can be
+ represented as a simple graph object.
+
+
+
+ Id Maps
+
+ An id map is used to associate an IRI with a value that allows easy
+ programmatic access. An id map may be used as a term value within a node object if the term
+ is defined with @container set to @id,
+ or an array containing both @id and @set.
+ The keys of an id map MUST be IRIs
+ (relative IRI, compact IRI (including blank node identifiers), or absolute IRI),
+ the keyword @none,
+ or a term which expands to @none,
+ and the values MUST be node objects.
+
+ If the value contains a property expanding to @id, it's value MUST
+ be equivalent to the referencing key. Otherwise, the property from the value is used as
+ the @id of the node object value when expanding.
+
+ Id Maps may also be used to map graph names to their
+ named graphs, if the term is defined with @container
+ set to an array containing both @graph and @id,
+ and optionally including @set. The value consists of the
+ node objects contained within the named graph
+ which is named using the referencing key.
+
+
+
+ Type Maps
+
+ A type map is used to associate an IRI with a value that allows easy
+ programmatic access. A type map may be used as a term value within a node object if the term
+ is defined with @container set to @type,
+ or an array containing both @type and @set.
+ The keys of a type map MUST be IRIs
+ (relative IRI, compact IRI (including blank node identifiers), or absolute IRI),
+ the keyword @none,
+ or a term which expands to @none,
+ and the values MUST be node objects.
+
+ If the value contains a property expanding to @type, and it's value
+ is contains the referencing key after suitable expansion of both the referencing key
+ and the value, then the node object already contains the type. Otherwise, the property from the value is
+ added as a @type of the node object value when expanding.
+
+
+
+
+
+ Context Definitions
+
+ A context definition defines a local context in a
+ node object.
+
+ A context definition MUST be a JSON object whose
+ keys MUST be either terms, compact IRIs, absolute IRIs,
+ or one of the keywords @language, @base,
+ @vocab, or @version.
+
+ If the context definition has an @language key,
+ its value MUST have the lexical form described in [[!BCP47]] or be null.
+
+ If the context definition has an @base key,
+ its value MUST be an absolute IRI, a relative IRI,
+ or null.
+
+ If the context definition has an @vocab key,
+ its value MUST be a absolute IRI, a compact IRI,
+ a blank node identifier,
+ an empty string (""),
+ a term, or null.
+
+ If the context definition has an @version key,
+ its value MUST be a number with the value 1.1.
+
+ The value of keys that are not keywords MUST be either an
+ absolute IRI, a compact IRI, a term,
+ a blank node identifier, a keyword, null,
+ or an expanded term definition.
+
+ An expanded term definition is used to describe the mapping
+ between a term and its expanded identifier, as well as other
+ properties of the value associated with the term when it is
+ used as key in a node object.
+
+ An expanded term definition MUST be a JSON object
+ composed of zero or more keys from
+ @id,
+ @reverse,
+ @type,
+ @language,
+ @context,
+ @prefix, or
+ @container. An
+ expanded term definition SHOULD NOT contain any other keys.
+
+ If the term being defined is not a compact IRI or
+ absolute IRI and the active context does not have an
+ @vocab mapping, the expanded term definition MUST
+ include the @id key.
+
+ If the expanded term definition contains the @id
+ keyword, its value MUST be null, an absolute IRI,
+ a blank node identifier, a compact IRI, a term,
+ or a keyword.
+
+ If an expanded term definition has an @reverse member,
+ it MUST NOT have @id or @nest members at the same time,
+ its value MUST be an absolute IRI,
+ a blank node identifier, a compact IRI, or a term. If an
+ @container member exists, its value MUST be null,
+ @set, or @index.
+
+ If the expanded term definition contains the @type
+ keyword, its value MUST be an absolute IRI, a
+ compact IRI, a term, null, or one of the
+ keywords @id or @vocab.
+
+ If the expanded term definition contains the @language keyword,
+ its value MUST have the lexical form described in [[!BCP47]] or be null.
+
+ If the expanded term definition contains the @container
+ keyword, its value MUST be either
+ @list,
+ @set,
+ @language,
+ @index,
+ @id,
+ @graph,
+ @type, or be
+ null
+
+ or an array containing exactly any one of those keywords, or a
+ combination of @set and any of @index,
+ @id, @graph, @type,
+ @language in any order
+ .
+ @container may also be an array
+ containing @graph along with either @id or
+ @index and also optionally including @set.
+ If the value
+ is @language, when the term is used outside of the
+ @context, the associated value MUST be a language map.
+ If the value is @index, when the term is used outside of
+ the @context, the associated value MUST be an
+ index map.
+
+ If an expanded term definition has an @context member,
+ it MUST be a valid context definition.
+
+ If the expanded term definition contains the @nest
+ keyword, its value MUST be either @nest, or a term
+ which expands to @nest.
+
+ If the expanded term definition contains the @prefix
+ keyword, its value MUST be true or false.
+
+ Terms MUST NOT be used in a circular manner. That is,
+ the definition of a term cannot depend on the definition of another term if that other
+ term also depends on the first term.
+
+ See for further discussion on contexts.
+
+
+
+
+