5. Basic Concepts
5.1 The Context
In JSON-LD, a context is used to map terms, i.e., properties with associated
values in an JSON document, to IRIs.
The Web uses IRIs for unambiguous identification. The
idea is that these terms mean something that may be of use to other developers and that it is useful to
give them an unambiguous identifier. That is, it is useful for terms to expand to IRIs so that
developers don't accidentally step on each other's vocabulary terms and other resources. Furthermore, developers, and
machines, are able to use this IRI (by plugging it directly into a web browser, for instance) to go to
the term and get a definition of what the term means. This mechanism is analogous to the way we can use
WordNet today to see the definition of words in the English language.
Developers and machines need the same sort of definition of terms. IRIs provide a way to
ensure that these terms are unambiguous. For example, the term 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.
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 terms ("")
is discouraged as not all programming languages are able to handle empty
property names.
In a JSON-LD document, the mapping between terms and
IRIs is typically collected in a context definition
that would look something like this:
Example 1: Context definition
{
"@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"
},
}
}
Let's assume that a developer starts with the following JSON document:
Example 2: Sample JSON document
{
"name": "Manu Sporny",
"homepage": "http://manu.sporny.org/",
"depiction": "http://twitter.com/account/profile_image/manusporny"
}The developer can add a single line to the JSON document above
to reference the context and transform it into a JSON-LD document:
Example 3: Referencing a JSON-LD 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"
}The additions above transform the previous JSON document into a JSON document
with added semantics because the @context specifies how the
name, homepage, and depiction
terms map to IRIs.
Mapping those keys to IRIs gives the data global context. If two
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, language or additional information
for certain terms.
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 simply discarded when the document
is used as an external JSON-LD context document
(see 6.4 Referencing Contexts from JSON Documents).
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.
Example 4: In-line context definition
{
"@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"
}Contexts may be used at any time a node object is defined.
In particular, a JSON-LD document may define more than one context,
as in the following example:
Example 5: Multiple separate contexts
[
{
"@context": "http://example.org/contexts/person.jsonld",
"name": "Manu Sporny",
"homepage": "http://manu.sporny.org/",
"depiction": "http://twitter.com/account/profile_image/manusporny"
},
{
"@context": "http://example.org/contexts/place.jsonld",
"name": "The Empire State Building",
"description": "The Empire State Building is a 102-story landmark in New York City.",
"geo": {
"latitude": "40.75",
"longitude": "73.98"
}
}
]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.
Example 6: Scoped contexts within node objects
{
"@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, the name prefix is overridden in the
more deeply nested details structure. Note that this is
rarely a good authoring practice and is typically used when there exist
legacy applications that depend on the specific structure of the
JSON object. If a term is re-defined within a
context, all previous rules associated with the previous definition are
removed. If that term is re-defined to null,
the term is effectively removed from the list of
terms defined in the active context.
A node object may specify multiple contexts, using an
array, processed in order. The set of contexts defined within a specific node object are
referred to as local contexts. Setting the context to null
effectively resets the active context to an empty context. The
active context refers to the accumulation of local 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:
Example 7: Combining external and local contexts
{
"@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"
}Note
To ensure the best possible performance, it is a best practice to
put the context definition at the top of the JSON-LD document. If it isn't listed
first, processors have to save each key-value pair until the context is processed.
This creates a memory and complexity burden for certain types of
low-memory footprint JSON-LD processors.
5.2 From JSON to JSON-LD
If a set of terms such as, name,
homepage, and depiction,
are defined in a context, and that context is used to resolve the
names in JSON objects, machines are able to automatically expand the terms to
something unambiguous like this:
Example 8: Expanded terms
{
"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"
}Doing this allows JSON to be unambiguously machine-readable without
requiring developers to drastically change their workflow. A JSON object
used to define property values of a node is called a node object.
Note
The example above does not use the @id keyword
to identify the node being described above. This type of node is called a
blank node. It is advised that all node objects
in JSON-LD are identified by IRIs via the @id
keyword unless the data is not intended to be linked to from other data sets.
5.3 IRIs
IRIs (Internationalized Resource Identifiers) are fundamental to Linked Data as
that is how most nodes and properties
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 a JSON object that have a mapping in the active context expand to an IRI. If there's a
@vocab
mapping in the active context also terms without an explicit mapping
in the active context are expanded to an IRI.
- 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 in effect that identify the value as an
@id.
IRIs may be represented as an absolute IRI or a relative IRI.
An absolute IRI is defined in [RFC3987] 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 all relative IRIs are resolved relative to the
base 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:
Example 9: IRI as a key
{
...
"http://xmlns.com/foaf/0.1/name": "Manu Sporny",
...
}In the example above, the key http://xmlns.com/foaf/0.1/name is interpreted
as an IRI because it contains a colon
(:) and the 'http' prefix does not exist in
the context.
Term expansion occurs for IRIs if the value matches a term defined within the
active context:
Example 10: Term expansion from context definition
{
"@context":
{
"name": "http://xmlns.com/foaf/0.1/name"
...
},
"name": "Manu Sporny",
"status": "trollin'",
...
}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.
Prefixes are expanded when the form of the value is a
compact IRI represented as a prefix:suffix
combination, and the prefix matches a term defined within the
active context:
Example 11: Prefix expansion
{
"@context":
{
"foaf": "http://xmlns.com/foaf/0.1/"
...
},
"foaf:name": "Manu Sporny",
...
}foaf:name above will automatically expand out to the IRI
http://xmlns.com/foaf/0.1/name. See 6.1 Compact IRIs for more details.
It is often common that all types and properties come from the same vocabulary. JSON-LD's
@vocab keyword allows to set a common prefix to be used for all properties and types
that neither match a term nor a compact IRI or an absolute IRI
(i.e., do not contain a colon).
Example 12: Using a common vocabulary prefix
{
"@context": {
"@vocab": "http://xmlns.com/foaf/1.0/"
},
"@type": "Person",
"name": "Manu Sporny",
}An IRI is generated when a JSON object is used in the
value position that contains an @id keyword:
Example 13: Expanded IRI definition
{
...
"homepage": { "@id": "http://manu.sporny.org" }
...
}Specifying a JSON object with an
@id key is used to identify that node using an
IRI. When the object has only the @id, it
is called a node object. This facility may also be used to link to another
node object using a mechanism called
embedding, which is covered in the section titled
6.10 Embedding.
If type coercion rules are specified in the @context for
a particular term or property IRI, an IRI is generated:
Example 14: Type coercion
{
"@context":
{
...
"homepage":
{
"@id": "http://xmlns.com/foaf/0.1/homepage",
"@type": "@id"
}
...
}
...
"homepage": "http://manu.sporny.org/",
...
}In the example above, even though the value
http://manu.sporny.org/ is expressed as a JSON
string, the type coercion rules will transform
the value into an IRI when generating the JSON-LD graph.
5.4 Node Identifiers
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 of
Linked 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 an IRI 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.
The node of a JSON object is identified using the @id
keyword:
Example 15: Identifying a node
{
"@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 contains a node object identified by the IRI
http://example.org/people#joebob.
Once defined, the node's unique identifier can be used to refer to
it from other parts of the document or from external documents, using
a node object that only contains an @id key:
Example 16: Referencing a node using its unique identifier
{
"@context": ...,
"@graph": [
{
"@id": "http://example.org/library",
"@type": "ex:Library",
"ex:contains": {"@id": "http://example.org/library/the-republic"}
}, {
"@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"}
}, {
"@id": "http://example.org/library/the-republic#introduction",
"@type": "ex:Chapter",
"dc:description": "An introductory chapter on The Republic.",
"dc:title": "The Introduction"
}
]
}
}5.5 Specifying the Type
The type of a particular node can be specified using the @type
keyword. In Linked Data, types are uniquely
identified with an IRI.
Example 17: Specifying the type for a node
{
...
"@id": "http://example.org/people#joebob",
"@type": "http://xmlns.com/foaf/0.1/Person",
...
}A node can be assigned more than one type by using the following markup
pattern:
Example 18: Specifying multiple types for a node
{
...
"@id": "http://example.org/places#BrewEats",
"@type": ["http://schema.org/Restaurant", "http://schema.org/Brewery"]
...
}The value of a @type key may also be a term defined in the active context:
Example 19: Using a term to specify the type
{
"@context": "http://json-ld.org/contexts/person.jsonld",
"@id": "http://manu.sporny.org/i/public",
"@type": "Person",
"name": "Manu Sporny",
"homepage": "http://manu.sporny.org/",
"depiction": "http://twitter.com/account/profile_image/manusporny"
}5.6 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.
Firstly, it is possible to define a default language for a JSON-LD document
by setting the @language key in the @context or in a
term definition:
Example 20: Setting the default language of a JSON-LD document
{
"@context":
{
...
"@language": "ja"
},
"name": "花澄",
"occupation": "科学者"
}The example above would associate the ja language
code with the two strings 花澄 and 科学者.
Languages codes are defined in [BCP47].
It is possible to override the default language by using an expanded value:
Example 21: Overriding default language using an expanded value
{
"@context": {
...
"@language": "ja"
},
"name": "花澄",
"occupation": {
"@value": "Scientist",
"@language": "en"
}
}It is also possible to override the default language or specify a plain
value by omitting the @language tag or setting it to
null when expressing the expanded value:
Example 22: Removing language information using an expanded value
{
"@context": {
...
"@language": "ja"
},
"name": {
"@value": "Frank"
},
"occupation": {
"@value": "Ninja",
"@language": "en"
},
"speciality": "手裏剣"
}Please note that language associations can only be applied to plain
literal strings. That is,
typed values or values that are subject
to 6.6 Type Coercion cannot be language tagged.
To clear the default language for a subtree, @language can
be set to null in a local context as follows:
Example 23: Clearing default language
{
"@context": {
...
"@language": "ja"
},
"name": "花澄",
"details": {
"@context": {
"@language": null
},
"occupation": "Ninja"
}
}6. Advanced Concepts
This section is normative.
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.
6.1 Compact IRIs
Terms in Linked Data documents may draw from
a number of different vocabularies.
At times, declaring every single term that a document uses can require the
developer to declare tens, if not hundreds of potential
vocabulary terms 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 the
terms, and the second is the serialized size of the
context if it is specified inline. In order to address these issues,
the concept of a compact IRI is introduced.
A compact IRI is a way of expressing an IRI
using a prefix and suffix separated by a colon (:) which is
similar to the CURIE Syntax
in [RDFA-CORE]. 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 out to the IRI http://xmlns.com/foaf/0.1/name.
Instead of having to remember and type out the entire IRI, the developer
can instead use the prefix in their JSON-LD markup.
Terms are interpreted as compact IRIs if they contain at least one
colon and the first colon is not followed by two slashes (//, as in
http://example.com). To generate the full IRI,
the value is first split into a prefix and suffix at the first
occurrence of a colon (:). If the active context
contains a term mapping for prefix, an IRI is generated by
prepending the mapped prefix to the (possibly empty) suffix
using textual concatenation. If no prefix mapping is defined, the value is interpreted
as an absolute IRI. If the prefix is an underscore
(_), the IRI remains unchanged.
Consider the following example:
Example 24: Compact IRIs
{
"@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 different vocabularies
are referred to using prefixes. Those prefixes are then used as type and
property values using the compact IRI prefix:suffix notation.
It's also possible to use compact IRIs within the context as shown in the
following example:
Example 25: Using vocabularies
{
"@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"
}6.2 Typed Values
A value with an associated type, also known as a
typed value, is indicated by associating a value with
an IRI which indicates the value's type. Typed values may be
expressed in JSON-LD in three ways:
- By utilizing the
@type keyword when defining
a term within a @context section.
- By utilizing an expanded typed value.
- By using a native JSON type such as number, true, or false.
The first example uses the @type keyword to associate a
type with a particular term in the @context:
Example 26: Expanded term definition with type coercion
{
"@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",
...
}The modified key's value above is automatically type coerced to a
datetime value because of the information specified in the
@context.
The second example uses the expanded form of setting the type information
in the body of a JSON-LD document:
Example 27: Expanded value with type
{
"@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 the value
2010-05-29T14:17:39+02:00 with the type
http://www.w3.org/2001/XMLSchema#dateTime. Note that it is
also possible to use a term or a compact IRI to
express the value of a type.
The @type keyword is also used to associate a type
with a node. The concept of a node type and
a value 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
inherently different.
Example 28: Example demonstrating the context-sensitivity for @type
{
...
"@id": "http://example.org/posts#TripToWestVirginia",
"@type": "http://schema.org/BlogPosting",
"modified":
{
"@value": "2010-05-29T14:17:39+02:00",
"@type": "http://www.w3.org/2001/XMLSchema#dateTime"
}
...
}The first use of @type associates a node type
(http://schema.org/BlogPosting) with the node,
which is expressed using the @id keyword.
The second use of @type associates a value type
(http://www.w3.org/2001/XMLSchema#dateTime) with the
value expressed using the @value keyword. As a
general rule, when @value and @type are used in
the same JSON object, the @type
keyword is expressing a value type.
Otherwise, the @type keyword is expressing a
node type.
6.3 Language-tagged Strings
A string with an associated language, also known as a
language-tagged string, is indicated by associating a string with
a language code as defined in [BCP47]. Language-tagged strings may be
expressed in JSON-LD in four ways:
- By defining a global language using the
@language
keyword within a @context section.
- By utilizing the
@language keyword when defining
a term within a @context section.
- By utilizing an expanded language-tagged string.
- By utilizing a language map, provided the underlying
term is defined with a @container
keyword whose value is @language within
a @context section.
The first example uses the @language keyword to associate a
type with a particular term in the @context:
Example 29: Expanded term definition with language coercion
{
"@context":
{
"title":
{
"@id": "http://purl.org/dc/terms/title",
"@language": "en"
}
},
...
"title": "JSON-LD Syntax",
...
}The modified key's value above is automatically
language coerced to a English value because of the information specified in
the @context.
The second example uses the expanded form of setting the language information
in the body of a JSON-LD document:
Example 30: Expanded value with language
{
"@context":
{
"title":
{
"@id": "http://purl.org/dc/terms/title"
}
},
...
"title":
{
"@value": "JSON-LD Syntax",
"@language": "en"
}
...
}Both examples above would generate the value JSON-LD Syntax
tagged with the language en; which is the [BCP47] code
for the English language.
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, language maps
may be utilized.
Example 31: Language map expressing a property in three languages
{
"@context":
{
"title":
{
"@id": "http://purl.org/dc/terms/title",
"@container": "@language"
}
},
...
"title":
{
"en": "JSON-LD Syntax",
"ru": "JSON-LD Синтаксис",
"ja": "JSON-LDの構文"
}
...
}In the example above, the title is expressed in three languages; English,
Russian, and Japanese. To access the data above in a programming language
supporting dot-notation accessors for object properties, a developer may
use the property.language pattern. For example, to access the
Japanese version of the title, a developer would use the following code
snippet: obj.title.ja.
6.4 Referencing Contexts from JSON Documents
Ordinary JSON documents can be transformed into JSON-LD documents by referencing
to an external JSON-LD context in an HTTP Link Header. Doing this
allows JSON to be unambiguously machine-readable without requiring developers to
drastically change their workflow and provides an upgrade path for existing
infrastructure without breaking existing clients that rely on the application/json
media type.
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
Header [RFC5988] using the http://www.w3.org/ns/json-ld#context link relation.
The referenced document must have a top-level node object. The
@context subtree within that object is added to the top-level
node object of the referencing document. If an array is at the top-level of the
referencing document and its items are node 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.
The following example demonstrates the use of an external context with an
ordinary JSON document:
Example 32: Specifing context through HTTP header
GET /ordinary-json-document.json HTTP/1.1
Host: example.com
Accept: application/ld+json,application/json,*/*;q=0.1
====================================
HTTP/1.0 200 OK
...
Content-Type: application/json
Link: <http://json-ld.org/contexts/person.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"
{
"name": "Markus Lanthaler",
"homepage": "http://www.markus-lanthaler.com/",
"depiction": "http://twitter.com/account/profile_image/markuslanthaler"
}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.
6.5 Expanded Term Definition
Within a context definition, terms may be
defined using an expanded term definition to allow for additional information
associated with the term to be specified (see also
6.6 Type Coercion and
6.9 Sets and Lists).
Instead of using a string representation of an IRI, the IRI may be
specified using a JSON object having an @id key,
and a term, a compact IRI, or an
absolute IRI as value.
Example 33: Expanded term definition
{
"@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. This
may be used for 6.6 Type Coercion,
6.9 Sets and Lists, or to associate language
information with a term as shown in the following example:
Example 34: Expanded term definition with language
{
"@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 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.
Expanded terms may also be defined using compact IRIs or
absolute IRIs as keys. If the definition does not include an
@id key, 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
information with a compact IRI or an absolute IRI.
Note
While it is possible to define a
compact IRI, or an absolute IRI to expand to some
other unrelated IRI (for example, foaf:name expanding to
http://example.org/unrelated#species),
such usage is strongly discouraged.
6.6 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 type IRIs 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 6.5 Expanded Term Definition
using the @type key. The value of this key expands to an IRI.
Alternatively, the keyword @id may be used as value to indicate
that within the body of a JSON-LD document, a string value of a term coerced to
@id is to be interpreted as an IRI.
Terms or compact IRIs used as the value of a
@type key may be defined within the same context. This means that one may specify a
term like xsd and then use xsd:integer within the same
context definition.
The example below demonstrates how a JSON-LD author can coerce values to
typed values, IRIs and lists.
Example 35: Expanded term definition with types
{
"@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"
}
},
"@id": "http://example.com/people#john",
"name": "John Smith",
"age": "41",
"homepage":
[
"http://personal.example.org/",
"http://work.example.com/jsmith/"
]
}The markup shown above would generate the following data. The data has no inherent order
except for the values the http://xmlns.com/foaf/0.1/homepage property
which represent an ordered list.
| Subject |
Property |
Object |
Datatype |
|---|
| http://example.com/people#john |
http://xmlns.com/foaf/0.1/name |
John Smith |
|
| http://example.com/people#john |
http://xmlns.com/foaf/0.1/age |
41 |
http://www.w3.org/2001/XMLSchema#integer |
| http://example.com/people#john |
http://xmlns.com/foaf/0.1/homepage |
http://personal.example.org/ |
|
| http://work.example.com/jsmith/ |
|
Terms may also be defined using absolute IRIs or compact IRIs.
This allows coercion rules to be applied to keys which are not represented as a simple term.
For example:
Example 36: Term definitions using compact and absolute IRIs
{
"@context":
{
"foaf": "http://xmlns.com/foaf/0.1/",
"foaf:age":
{
"@id": "http://xmlns.com/foaf/0.1/age",
"@type": "xsd:integer"
},
"http://xmlns.com/foaf/0.1/homepage":
{
"@type": "@id"
}
},
"foaf:name": "John Smith",
"foaf:age": "41",
"http://xmlns.com/foaf/0.1/homepage":
[
"http://personal.example.org/",
"http://work.example.com/jsmith/"
]
}In this case the @id definition in the term definition is optional, but if it does exist, the compact IRI
or IRI is treated as a term (not a prefix:suffix construct)
so that the actual definition of a prefix becomes unnecessary. Type coercion is performed using
the unexpanded value of the key, which has to match exactly an entry in the active context.
Note
Keys in the context are treated as terms for the purpose of
expansion and value coercion. At times, this may result in multiple representations for the same expanded IRI.
For example, one could specify that dog and cat both expanded to http://example.com/vocab#animal.
Doing this could be useful for establishing different type coercion or language specification rules. It also allows a compact IRI (or even an
absolute IRI) to be defined as something else entirely. For example, one could specify that
the term http://example.org/zoo should expand to
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.
6.7 Property Generators
At times, an author may find that they need to express the same value for
multiple properties. The simplest approach to accomplish this goal would be
to do the following:
Example 37: Verbose expression of multiple properties with the same value
{
"@context":
{
"title1": "http://purl.org/dc/terms/title",
"title2": "http://schema.org/name",
"title3": "http://www.w3.org/2000/01/rdf-schema#label"
},
"@id": "http://example.com/book",
"title1": "The Count of Monte Cristo",
"title2": "The Count of Monte Cristo",
"title3": "The Count of Monte Cristo"
}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 generator to express a term that maps to
multiple properties in the JSON-LD graph.
This method can be accomplished by using the following markup pattern:
Example 38: Generating multiple properties using a single term
{
"@context":
{
"title": { "@id": [ "http://purl.org/dc/terms/title",
"http://schema.org/name",
"http://www.w3.org/2000/01/rdf-schema#label" ] }
},
"@id": "http://example.com/book",
"title": "The Count of Monte Cristo"
}While the term above is only used once outside of the @context,
the document above is equivalent to the following:
| Subject |
Property |
Object |
|---|
| http://example.com/book |
http://purl.org/dc/terms/title |
The Count of Monte Cristo |
| http://example.com/book |
http://schema.org/name |
The Count of Monte Cristo |
| http://example.com/book |
http://www.w3.org/2000/01/rdf-schema#label |
The Count of Monte Cristo |
6.8 IRI Expansion Within a Context
In general, normal IRI expansion rules apply
anywhere an IRI is expected (see 5.3 IRIs). Within
a context definition, this can mean that terms defined
within the context may also be used within that context as long as
there are no circular dependencies. For example, it is common to use
the xsd namespace when defining typed values:
Example 39: IRI expansion within a context
{
"@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, the xsd term is defined
and used as a prefix for the @type coercion
of the age property.
Terms may also be used when defining the IRI of another
term:
Example 40: Using a term to define the IRI of another term within a context
{
"@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
and IRIs may be used on the left-hand side of a
term definition.
Example 41: Using a compact IRI as a term
{
"@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, the compact IRI form is used in two different
ways.
In the first approach, foaf:age declares both the
IRI for the term (using short-form) as well as the
@type associated with the term. In the second
approach, only the @type associated with the term is
specified. The full IRI for
foaf:homepage is determined by looking up the foaf
prefix in the
context.
Absolute IRIs may also be used in the key position in a context:
Example 42: Associating context definitions with absolute IRIs
{
"@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 the absolute IRI to match above, the absolute IRI needs to be used in the JSON-LD document. Also note that foaf:homepage
will not use the { "@type": "@id" } declaration because
foaf:homepage is not the same as
http://xmlns.com/foaf/0.1/homepage. That is, terms
are looked up in a context using direct string comparison before the
prefix lookup mechanism is applied.
The only exception for using terms in the context is that
circular definitions are not allowed. That is,
a definition of term-1 cannot depend on the
definition of term-2 if term-2 also depends on
term-1. For example, the following context definition
is illegal:
Example 43: Illegal circular definition of terms within a context
{
"@context":
{
"term1": "term2:foo",
"term2": "term1:bar"
},
...
}6.9 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:
Example 44: Multiple values with no inherent order
{
...
"@id": "http://example.org/people#joebob",
"nick": [ "joe", "bob", "jaybee" ],
...
}The markup shown above would result in the following data being generated,
each relating the node to an individual value, with no inherent order:
| Subject |
Property |
Object |
|---|
| 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:
Example 45: Using an expanded form to set multiple values
{
"@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 data, again with
no inherent order:
| Subject |
Property |
Object |
Language |
|---|
| 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 @list keyword as follows:
Example 46: An ordered collection of values in JSON-LD
{
...
"@id": "http://example.org/people#joebob",
"foaf:nick":
{
"@list": [ "joe", "bob", "jaybee" ]
},
...
}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:
Example 47: Specifying that a collection is ordered in the context
{
"@context":
{
...
"nick":
{
"@id": "http://xmlns.com/foaf/0.1/nick",
"@container": "@list"
}
},
...
"@id": "http://example.org/people#joebob",
"nick": [ "joe", "bob", "jaybee" ],
...
}Note
List of lists 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.
Similarly to @list, there exists the keyword @set to
describe unordered sets. While its use in the body of a JSON-LD document
represents just syntactic sugar 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 an array - even if there is just a
single value that would otherwise be optimized to a non-array form in a
6.17 Compact Document Form. 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.
Note
The use of @container in the body of a JSON-LD
document has no meaning and is not allowed by the JSON-LD grammar (see B. JSON-LD Grammar).
6.10 Embedding
Embedding is a JSON-LD feature that allows an author to
use node objects as
property values. This is a commonly used mechanism for
creating a parent-child relationship between two nodes.
The example shows two nodes related by a property from the first node:
Example 48: Embedding a node object as property value of another node object
{
...
"name": "Manu Sporny",
"knows":
{
"@type": "Person",
"name": "Gregg Kellogg",
}
...
}
A node object, like the one used above, may be used in
any value position in the body of a JSON-LD document.
6.11 Named Graphs
At times, it is necessary to make statements about a JSON-LD graph
itself, rather than just a single node. This can be done by
grouping a set of nodes using the @graph
keyword. A developer may also name data expressed using the
@graph keyword by pairing it with an
@id keyword as shown in the following example:
Example 49: Identifying and making statements about a graph
{
"@context": {
"generatedAt": "http://www.w3.org/ns/prov#generatedAtTime",
"Person": "http://xmlns.com/foaf/0.1/Person",
"name": "http://xmlns.com/foaf/0.1/name",
"knows": "http://xmlns.com/foaf/0.1/knows",
"xsd": "http://www.w3.org/2001/XMLSchema#"
},
"@id": "http://example.org/graphs/73",
"generatedAt": { "@value": "2012-04-09", "@type": "xsd:date" },
"@graph":
[
{
"@id": "http://manu.sporny.org/i/public",
"@type": "Person",
"name": "Manu Sporny",
"knows": "http://greggkellogg.net/foaf#me"
},
{
"@id": "http://greggkellogg.net/foaf#me",
"@type": "Person",
"name": "Gregg Kellogg",
"knows": "http://manu.sporny.org/i/public"
}
]
}The example above expresses a named JSON-LD graph
that is identified by the IRI
http://example.org/graphs/73. That graph is composed of the
statements about Manu and Gregg. Metadata about the graph itself is also
expressed via the generatedAt property, which specifies when
the graph was generated. An alternative view of the
information above is represented in table form below:
| Graph |
Subject |
Property |
Object |
Datatype |
|---|
| http://example.org/graphs/73 |
http://example.org/graphs/73 |
http://www.w3.org/ns/prov#generatedAtTime |
2012-04-09 |
http://www.w3.org/2001/XMLSchema#date |
| http://example.org/graphs/73 |
http://manu.sporny.org/i/public |
http://www.w3.org/2001/XMLSchema#type |
http://xmlns.com/foaf/0.1/Person |
|
| http://example.org/graphs/73 |
http://manu.sporny.org/i/public |
http://xmlns.com/foaf/0.1/name |
Manu Sporny |
|
| http://example.org/graphs/73 |
http://manu.sporny.org/i/public |
http://xmlns.com/foaf/0.1/knows |
http://greggkellogg.net/foaf#me |
|
| http://example.org/graphs/73 |
http://greggkellogg.net/foaf#me |
http://www.w3.org/2001/XMLSchema#type |
http://xmlns.com/foaf/0.1/Person |
|
| http://example.org/graphs/73 |
http://greggkellogg.net/foaf#me |
http://xmlns.com/foaf/0.1/name |
Gregg Kellogg |
|
| http://example.org/graphs/73 |
http://greggkellogg.net/foaf#me |
http://xmlns.com/foaf/0.1/knows |
http://manu.sporny.org/i/public |
|
When @graph is used in a document's top-level object which
has no other properties that are mapped
to an IRI or a keyword it is considered to
express the otherwise implicit default graph. This mechanism can be useful
when a number of nodes thay may not directly
relate to one another through a property or where embedding
is not desirable to the application. For example:
Example 50: Using @graph to explicitly express the default graph
{
"@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 each node object
references the other. Using the @graph keyword
allows multiple nodes to be defined within an
array, and allows the use of a shared context.
This is equivalent to using multiple
node objects in array and defining
the @context within each node object:
Example 51: Context needs to be duplicated if @graph is not used
[
{
"@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"
}
]6.12 Identifying Blank Nodes
At times, it becomes necessary to be able to express information without
being able to specify the node. This type of node is called a blank node
(see Section 3.4: Blank Nodes
of [RDF-CONCEPTS]). In JSON-LD, blank node identifiers are
automatically created if a node is not specified using the @id keyword.
However, authors may provide identifiers for blank nodes
by using the special _ (underscore) prefix. This allows one
to reference the node locally within the document, but makes it impossible to reference
the node from an external document. The blank node identifier is scoped
to the document in which it is used.
Example 52: Specifying a local blank node identifier
{
...
"@id": "_:foo",
...
}The example above would set the node to _:foo, which can
then be used elsewhere in the JSON-LD document to refer back to the
blank node. If a developer finds that they refer to the blank node
more than once, they should consider naming the node using a dereferenceable
IRI so that it can also be referenced from other documents.
6.13 Aliasing Keywords
Each of the JSON-LD keywords,
except for @context, may be aliased to application-specific
keywords. This feature allows legacy JSON content to be utilized
by JSON-LD by re-using JSON keys that already exist in legacy documents.
This feature also allows developers to design domain-specific implementations
using only the JSON-LD context.
Example 53: Aliasing keywords
{
"@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 @type
keywords have been given the aliases url and
a, respectively.
6.14 Data Annotations
It is common for developers using JSON to organize their data in ways
that makes working with the data more efficient. It is often that these methods
of organizing data are not meant to express Linked Data, but should survive
transformation by JSON-LD. For example, if a developer
organizes employees in a JSON-LD document by a company-issued ID number,
JSON-LD should not destroy that 'database index' when transforming the data.
Data annotations allow content that would otherwise be removed from
a JSON-LD graph to be
preserved by instructing the JSON-LD processor to syntactically preserve
the annotation information and continue processing deeper into the JSON
data structure.
Example 54: Data annotations
{
"@context":
{
"schema": "http://schema.org/",
"Article": "schema:Blog",
"name": "schema:name",
"articleBody": "schema:articleBody",
"wordCount": "schema:wordCount",
"commentCount": "http://example.com/schema/wordCount",
"blogPost": {
"@id": "schema:blogPost",
"@container": "@annotation"
},
"@id": "http://example.com/",
"@type": "Blog",
"name": "World Financial News",
"blogPost": {
"en": {
"@id": "http://example.com/posts/1/en",
"articleBody": "World commodities were up today with heavy trading of crude oil...",
"wordCount": 1539,
"commentCount": 64
},
"de": {
"@id": "http://example.com/posts/1/de",
"articleBody": "Welt Rohstoffe waren bis heute mit schweren Handel mit Rohöl...",
"wordCount": 1204,
"commentCount": 23
}
}
}In the example above, the blogPost term has
been marked as a data annotation container. The en,
de, and ja keys will effectively be ignored
semantically, but preserved syntactically, by the JSON-LD Processor as
annotations. The interpretation of the data above is expressed in
the table below. Note how the annotations do not appear in the Linked Data
below, but would continue to exist if the document were compacted or expanded
using a JSON-LD processor:
| Subject |
Property |
Object |
Datatype |
|---|
| http://example.com/ |
http://www.w3.org/1999/02/22-rdf-syntax-ns#type |
http://schema.org/Blog |
|
| http://example.com/ |
http://schema.org/name |
World Financial News |
|
| http://example.com/ |
http://schema.org/blogPost |
http://example.com/posts/1/en |
|
| http://example.com/ |
http://schema.org/blogPost |
http://example.com/posts/1/de |
|
| http://example.com/posts/1/en |
http://schema.org/articleBody |
World commodities were up today with heavy trading of crude oil... |
|
| http://example.com/posts/1/en |
http://schema.org/wordCount |
1539 |
http://www.w3.org/2001/XMLSchema#integer |
| http://example.com/posts/1/en |
http://example.com/schema/commentCount |
64 |
http://www.w3.org/2001/XMLSchema#integer |
| http://example.com/posts/1/de |
http://schema.org/articleBody |
Welt Rohstoffe waren bis heute mit schweren Handel mit Rohöl... |
|
| http://example.com/posts/1/de |
http://schema.org/wordCount |
1204 |
http://www.w3.org/2001/XMLSchema#integer |
| http://example.com/posts/1/de |
http://example.com/schema/commentCount |
23 |
http://www.w3.org/2001/XMLSchema#integer |
6.15 Explicitly Ignoring Data
At times, it becomes necessary to explicitly ignore data expressed in JSON
documents because it has no semantic meaning. For example, when the
@vocab keyword is used, every key in a JSON-LD object is
appended to the vocabulary IRI. The author may not want that
behavior to apply to every key, and it may be easier to specify just the keys
that they want the JSON-LD processor to ignore. For this purpose, an author
may associate the null keyword with a term in the
JSON-LD Context.
Example 55: Using the null keyword to ignore data
{
"@context":
{
"@vocab": "http://schema.org/",
"databaseId": null
},
"name": "Manu Sporny",
"description": "That guy",
"gender": "Male",
"databaseId": "23987520"
}In the example above, the author has used @vocab as the base
IRI for all terms in the document, but has expressed that the
databaseId value should not be processed by the JSON-LD processor
by associating it with the null keyword in the JSON-LD Context.
B. JSON-LD Grammar
This section is normative
This section is an attempt to formalize
a normative grammar for JSON-LD.
This appendix restates the syntactic conventions described in the
previous sections more formally.
Note
The JSON-LD context allows keywords
6.13 Aliasing Keywords). 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.
A JSON-LD document must be a valid JSON document as described
in [RFC4627].
A JSON-LD document must be a single node object
or a JSON array containing a set of one or more
node objects.
B.1 Node Object
A node object represents zero or more properties of a
node in the JSON-LD graph serialized by the
JSON-LD document.
A JSON Object is a node object if
it exists outside of the JSON-LD Context and:
- it does not contain the
@value, @list,
@annotation, or @set keywords, or
- it does not contain the
@graph keyword and is
the top-most JSON Object in the JSON-LD document.
The properties of a node in the JSON-LD graph
may be spread among different node objects
within a document. When that happens,
the keys of the different node objects
are merged to create the properties of the resulting node.
A node object must be a JSON object that contains
one or more key-value pairs. Keys must either be
IRIs,
compact IRIs,
terms valid in the active context, or
one of the following keywords:
@context,@graph,@id, or@type
If the node object contains the @context
key, its value must be one of the following:
If the node object contains the @id key,
its value must be
an IRI,
a compact IRI (including blank node identifiers), or
a term defined in the active context expanding
into an IRI or a blank node identifier.
See 5.4 Node Identifiers, 6.1 Compact IRIs,
and 6.12 Identifying Blank Nodes for further discussion on
@id values.
If the node object contains the @type
key, its value must be either
an absolute IRI,
a compact IRI (excluding blank node identifier),
a term defined in the active context expanding into an absolute IRI, or
an array of any of these.
See 5.5 Specifying the Type for further discussion on
@type 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 label of a named graph.
See 6.11 Named Graphs for further discussion on
@graph values.
A JSON-LD document must not contain any keyword
that expands to another keyword.
Keys in a node object that are not
keywords must expand to an absolute IRI
using the active context. The values associated with these keys
must be one of the following:
- string,
- number,
- true,
- false,
- null,
- node object,
- expanded typed value,
- expanded language-tagged string,
- list or set,
- an array of zero or more of the possibilities above,
- a language map, or
- an annotation map
B.2 Term
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.
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 use of
empty terms ("") is discouraged as not all programming languages
are able to handle empty property names.
See 5.1 The Context and 5.3 IRIs for further discussion
on mapping terms to IRIs.
B.3 Language Map
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. The keys of a
language map must be lowercase [BCP47]
strings with an associated value that is any
of the following types:
See 6.3 Language-tagged Strings for further discussion on language maps.
B.4 Annotation Map
An annotation map allows keys that have no semantic meaning,
but should be preserved regardless, to be used in JSON-LD documents.
An annotation map may
be used as a term value within a node object if the
term is defined with @container set to @annotation.
The keys of a annotation map must be
strings with an associated value that is any
of the following types:
See 6.14 Data Annotations for further information on this
topic.
B.6 List and Set Values
A list represents an ordered set of values.
A set represents an unordered set of values.
Unless otherwise specified (typically through the use of a list),
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 a @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 array form.
A list must be a JSON object that contains a single key-value pair where the key is @list.
A set must be a JSON object that contains a single key-value pair where the key is @set.
In both cases, the value associated with the key must be an array of any of the following:
See 6.9 Sets and Lists for further discussion on List and Set Values.
B.7 Context Definition
A context definition defines a local context in a node object.
A context definition must be a JSON object
containing one or more key-value pairs. Keys must either be
terms or @language or @vocab keywords.
If the context definition has a @language key,
its value must have the lexical form described in [BCP47] or be null.
If the context definition has a @vocab key,
its value must have the lexical form of absolute IRI or be null.
Term values must be either a
string, 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 should be a JSON object
composed of zero or more keys from @id,
@type, @language or @container. An
expanded term definition should not contain any other keys.
If the term definition is not null, a compact IRI, or an absolute IRI,
the expanded term
definition must include the @id key.
If the expanded term definition contains the @id keyword,
its value must be null, an IRI, a compact IRI, a term defined in the defining context definition or the active context, or an array composed of any of the previous allowed values.
If the expanded term definition contains the @type keyword,
its value must be an absolute IRI, a compact IRI, a term defined in the defining context definition or the active context, or the @id keyword.
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, @annotation, or be null.
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
@annotation, when the term is used outside of
the @context, the associated value must be an
annotation map.
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 5.1 The Context and 6.5 Expanded Term Definition
for further discussion on contexts.
