JSON-LD is a way of expressing
There are a number of best practices that can ensure that developers
will generate good
The following is an explanation of the general terminology used in this - document. Many of the terms should be familiar to developers that have - used JSON:
+This document uses terms defined in JSON [[!RFC4627]] described in the + following list. Refer to the JSON grammar section in JSON for formal + definitions.
null value is processed in a special way in JSON-LD.
- Unless otherwise specified, a JSON-LD processor MUST act as if a
- key-value pair in the body of a JSON-LD document was never declared
- when the value equals null. If @value,
+ null value. Unless otherwise specified, a key-value
+ pair in the body of a JSON-LD document whose value is null
+ has the same meaning as if the key-value pair was not defined. If @value,
@list, or @set is set to null in
expanded form, then the entire @value,
- @list or @set and it has one or more keys other
- than @id. A node definition MAY be spread among different
- parts of a document or even between different documents.@id.@context@context keyword is described in detail in the section titled
.The JSON-LD Syntax specification describes the conformance criteria for JSON-LD documents (relevant to authors and authoring tool implementors).
+ +A
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL in this Recommendation have the meaning defined in [[!RFC2119]].
+ +In JSON-LD, a @ character SHOULD NOT be used
- as they might be used as "") is discouraged as not all programming languages are able to handle
- empty property names.
In JSON-LD, a
The Web uses
name may
map directly to the IRI http://xmlns.com/foaf/0.1/name. This allows JSON-LD documents to be constructed
using the common JSON practice of simple key-value pairs while ensuring that the data is useful outside of the
- page, API or database in which it resides. The value of a term mapping
- MUST be either; 1) a simple string with the lexical form of an @id, @type, @language, or @container keyword
- (all other keywords are ignored by a JSON-LD processor).
+ page, API or database in which it resides.
+
+Note that, to avoid forward-compatibility issues, terms starting with an @ character are to be avoided as they might be used as keywords in future versions of JSON-LD. Furthermore, the use of empty "")
+ is discouraged as not all programming languages are able to handle empty
+ property names.
These Linked Data
In a JSON-LD document, the mapping between
@@ -541,18 +538,19 @@The Context
developers use the same IRI to describe a property, they are more than likely expressing the same concept. This allows both developers to re-use each others' data without having to agree to how their data will interoperate on a -site-by-site basis. Contexts may also contain type information -for certainterm s as well as other processing instructions for -the JSON-LD processor. +site-by-site basis. Contexts may also contain type, language or additional information +for certainterms . -External JSON-LD context documents MAY contain extra information +
External JSON-LD context documents may contain extra information located outside of the
+@contextkey, such as documentation about the -terms declared in the document. When importing a -@contextvalue from an external JSON-LD context document, any extra -information contained outside of the@contextvalue MUST be discarded.terms declared in the document. Information contained +outside of the@contextvalue is simply discarded when the document +is used as an external JSON-LD context document +(see ). -Contexts MAY be specified in-line. This ensures that JSON-LD documents -can be processed when a JSON-LD processor does not have access to the Web.
+Contexts may also be specified in-line. This ensures that +
JSON-LD documents can be understood + even in the absence of a connection to the Web.@@ -579,12 +577,12 @@-The Context
-->Contexts MAY be used at any time a
node definition is defined. - Anode definition MAY specify multiple contexts, using an -array , which is processed in order. This is useful - when an author would like to use an existing context and add - application-specific terms to the existing context. Duplicate context -term s MUST be overridden using a last-defined-overrides +Contexts may be used at any time a
node definition is defined. + Anode definition may specify multiple contexts, using an +array , processed in order. + This is useful when an author would like to use an existing context + and add application-specific terms to the existing context. Duplicate context +terms are overridden using a last-defined-overrides mechanism.The Context legacy applications that depend on the specific structure of the-JSON object . If aterm is re-defined within a context, all previous rules associated with the previous definition are - removed. Aterm defined in a previous context MUST be removed, - if it is re-defined tonull. + removed. If thatterm is re-defined tonull, + theterm is effectively removed from the list of +terms defined in theactive context .The set of contexts defined within a specific
@@ -654,7 +653,7 @@node definition are - referred to aslocal context s. Setting the context tonull+ referred to aslocal contexts . Setting the context tonulleffectively resets theactive context to an empty context. The -active context refers to the accumulation oflocal context s +active context refers to the accumulation oflocal contexts that are in scope at a specific point within the document. The following example specifies an external context and then layers a local context on top of the external context:The Context
@@ -693,13 +692,12 @@ From JSON to JSON-LD
-If a set of
term s such as, name, +If a set of
terms such as, name, homepage, and depiction, are defined in acontext , and that context is used to resolve the names inJSON objects , machines are able to automatically expand the terms to @@ -684,7 +683,7 @@From JSON to JSON-LD
node definition .Node definitions do not require an@id.Node definitions that do not - contain an@idare known as anunlabeled nodes . + contain an@idare known asunlabeled nodes .IRIs
+ that is how most
IRIs (Internationalized Resource Identifiers are fundamental toLinked Data as - that is how mostnodes s andproperties - are identified.IRI s can be expressed in a variety of different ways in JSON-LD:nodes andproperties + are identified.IRIs can be expressed in a variety of different ways in JSON-LD:-
- Except within a
context definition,terms in the - key position in aJSON object that have a mapping in theactive context - are expanded to anIRI by JSON-LD processors. If there's a@vocab+ key position in aJSON object that have a mapping in theactive context expand to anIRI . If there's a@vocabmapping in the active context alsoterms without an explicit mapping in the active context are expanded to anIRI .- An
IRI is generated for thestring value specified using @@ -708,12 +706,11 @@IRIs
arecoercion rules in effect that identify the value as an@id.IRIs may be represented as an
+absolute IRI , arelative IRI , - acompact IRI , or aterm .IRIs may be represented as an
absolute IRI or arelative IRI .An
absolute IRI is defined in [[!RFC3987]] containing a scheme along with path and optional query and fragment segments. Arelative IRI is an IRI - that is relative to some otherabsolute IRI . In JSON-LD allrelative IRI s are resolved relative to the + that is relative to some otherabsolute IRI . In JSON-LD allrelative IRIs are resolved relative to thebase IRI 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:
@@ -753,14 +750,14 @@IRIs
-->+
Term s are case sensitive, and MUST be matched using a case-sensitive comparison.
Terms are case sensitive.JSON keys that do not expand to an absolute IRI are ignored, or removed in some cases, by the [[JSON-LD-API]]. However, JSON keys that do not include a mapping in the
-context are still considered valid expressions in JSON-LD documents - the keys just don't expand to unambiguous identifiers.
Prefix es are expanded when the form of the value is a +@@ -786,8 +783,7 @@
Prefixes are expanded when the form of the value is acompact IRI represented as aprefix:suffixcombination, and the prefix matches aterm defined within theactive context :IRIs
It is often common that all types and properties come from the same vocabulary. JSON-LD's
+ (i.e., do not contain a colon).@vocabkeyword allows to set a common prefix to be used for all properties and types that neither match aterm nor acompact IRI or anabsolute IRI - (i.e., do not contain a colon). The@vocabmapping MUST have a value of a simple string with the - lexical form of an absolute IRI.@@ -820,7 +816,7 @@IRIs
@idkey is used to identify thatnode using anIRI . When the object has only the@id, it is called anode reference . - This facility MAY also be used to link to another + This facility may also be used to link to anothernode definition using a mechanism calledembedding , which is covered in the section titled . @@ -852,7 +848,7 @@IRIs
In the example above, even though the value
+the value into an IRI when generating thehttp://manu.sporny.org/is expressed as a JSONstring , the typecoercion rules will transform -the value into an IRI when processed by a JSON-LD Processor.JSON-LD graph .
To be able to externally reference nodes in a graph, it is important that each node has
- an unambiguous identifier.
@id. A @id property defines properties of an
- The type of a particular node can be specified using the @type
-
@@ -969,11 +964,10 @@String Internationalization
The example above would associate the ja language
- code with the two
It is possible to override the default language by using the expanded -form of a value:
+It is possible to override the default language by using an
@@ -994,7 +988,7 @@String Internationalization
It is also possible to override the default language or specify a plain value by omitting the
+@languagetag or setting it to -nullwhen expressing the expanded value:nullwhen expressing theexpanded value :@@ -1016,10 +1010,10 @@-String Internationalization
-->Please note that language associations MUST only be applied to plain - literal
+string s. That is,typed value s - or values that are subject to - won't be language tagged.Please note that language associations can only be applied to plain + literal
strings . That is, +typed values or values that are subject + to cannot be language tagged.To clear the default language for a subtree,
@@ -1044,7 +1038,7 @@@languagecan be set tonullin alocal context as follows:String Internationalization
JSON-LD allows one to associate language information with
-
A JSON-LD document is first, and foremost, a JSON document - (as defined in [[!RFC4627]]), and any syntactically correct JSON document - MUST be processed by a conforming JSON-LD processor. However, JSON-LD +
A
-
@@ -1106,7 +1099,7 @@
Terms are interpreted as
Terms are interpreted as //, as in
http://example.com). To generate the full
_), the IRI remains unchanged. This effectively means that every term
- containing a colon will be interpreted by a JSON-LD processor as an IRI.
+ (_), the IRI remains unchanged.
Consider the following example:
Typed Values@@ -1250,7 +1242,7 @@
- By utilizing the
-@typekeyword when defining aterm within a@contextsection.- By utilizing the expanded form for specifying values.
+- By utilizing an
expanded typed value .- By using a native JSON type such as
number ,true , orfalse .Typed Values
express the value of a type.The
@typekeyword is also used to associate a type - with anode . The concept of annode type and + with anode . The concept of anode type and avalue type are different. This is similar to object-oriented programming languages where both scalar and structured types use the same class inheritance mechanism, even though scalar types and structured types are @@ -1293,7 +1285,7 @@Language-tagged Strings
A string with an associated language, also known as a
@@ -1302,11 +1294,11 @@language-tagged string , is indicated by associating a string with - an language code as defined in [[!BCP47]]. Language-tagged strings may be + a language code as defined in [[!BCP47]]. Language-tagged strings may be expressed in JSON-LD in four ways:Language-tagged Strings
keyword within a@contextsection.
@language @context section.@container @language when defining a @context section. This usage pattern is called a
- term is defined with a @container
+ @language within
+ a @context section.The first example uses the @language keyword to associate a
@@ -1367,7 +1359,7 @@
Systems that support multiple languages often need to express data values in
each language. Typically, such systems also try to ensure that developers have
a programatically easy way to navigate the datastructures for the
-language-specific data. In this case,
Referencing Contexts from JSON Documents-In order to use an external context with an ordinary JSON document, an author -MUST specify an
IRI to a valid JSON-LD document in an HTTP Link +MUST specify anIRI to a validJSON-LD document in an HTTP Link Header [[!RFC5988]] using thedescribedbylink relation. The referenced document MUST have a top-levelnode definition . The @@ -1452,7 +1444,8 @@Referencing Contexts from JSON Documents
-->
Please note that JSON-LD documents served with the application/ld+json
+
Please note that 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
describedby HTTP Link Header MUST be ignored for such documents.
Within a
Within a
Instead of using a string representation of an IRI, the IRI MAY be
-specified using a @id key.
-The value of the @id key MUST be either a
Instead of using a string representation of an IRI, the IRI may be
+specified using a @id key,
+and a
Expanded Term Definition
This allows additional information to be associated with the term. This
- MAY be used for ,
- ), or to associate language
+ may be used for ,
+ , or to associate language
information with a
Expanded Term Definitionen, and Nindža with the language codecs. The value ofname, Yagyū Muneyoshi wouldn't be associated with any language code since@languagewas reset to -null in the expanded term definition. +null in theexpanded term definition . -Expanded terms MAY also be defined using
compact IRIs or +Expanded terms may also be defined using
compact IRIs orabsolute IRIs as keys. If the definition does not include an@idkey, the expanded IRI is determined by performing expansion of the key - within the current active context. This mechanism is mainly used to associate type or language + within the currentactive context . This mechanism is mainly used to associate type or language information with acompact IRI or anabsolute IRI .While it is possible to define a @@ -1543,24 +1536,23 @@
Type Coercion
JSON-LD supports the coercion of values to particular data types. Type
coercion allows someone deploying JSON-LD to coerce the incoming or -outgoing values to the proper data type based on a mapping of data typeIRI s to -term s. Using type coercion, value representation is preserved without requiring +outgoing values to the proper data type based on a mapping of data typeIRIs to +terms . Using type coercion, value representation is preserved without requiring the data type to be specified with each piece of data.Type coercion is specified within an - using the
@typekey. The value of this key represents a type IRI and MUST take the form of - aterm ,compact IRI ,absolute IRI , or thekeyword @id. Specifying -@idindicates that within the body of a JSON-LD document, a string value of aterm coerced to + using the@typekey. The value of this key expands to anIRI . + Alternatively, thekeyword @idmay be used as value to indicate + that within the body of a JSON-LD document, a string value of aterm coerced to@idis to be interpreted as anIRI .+ context definition.
Terms orcompact IRIs used as the value of a -@typekey MAY be defined within the same context. This means that one may specify a +@typekey may be defined within the same context. This means that one may specify aterm likexsdand then usexsd:integerwithin the same - context definition - the JSON-LD processor will be able to determine the proper expansion for -xsd:integer.The example below demonstrates how a JSON-LD author can coerce values to -
+typed value s, IRIs and lists.typed values , IRIs and lists.@@ -1675,9 +1667,8 @@Type Coercion
http://example.org/river, but this usage is discouraged because it would lead to a great deal of confusion among developers attempting to understand the JSON-LD document. -Type coercion is performed using the unexpanded value of the key, - which MUST have an exact match for an entry in the -
+active context .Type coercion is performed using the unexpanded value of the key, which has to match exactly + an entry in the
active context .
Unfortunately, the approach above produces redundant data and would become a
publishing burden for large data sets.
In these situations, the author may use
-a
Property Generators
While the term above is only used once outside of the @context,
-a JSON-LD processor will internally transform the document above into
-the following set of statements:
-
See , ,
- and for further discussion on
- @id values.
If the @id
- key, it's value
- MUST be a
@id values.
@@ -2582,16 +2574,13 @@Node Definition
If the @type
- key, it's value
- MUST be either a
A JSON-LD processor SHOULD process non-conforming documents
- having @type values including @id key.
@type values.
@@ -2606,17 +2595,17 @@-Node Definition
} -->
See for further discussion on
- @type values.
If the @graph
- key, it's value MUST
- be a @id keyword,
- its value is used as the label of a named graph.
@id keyword,
+ its value is used as the label of a named graph.
+ See for further discussion on
+ @graph values.
-As a special case, if the
As a special case, if a @graph and @context, and the
See for further discussion on
- @graph values.
A JSON-LD document MUST NOT contain any
A
Other keys MUST expand to an
Keys in a
@set or @list
- definition (see ),A @id
- (or an alias for @id) is a
A
A @id (or an alias for
+ @id, see ).
The value of the @id key in a
See , ,
+ and for further discussion on
+ @id values.