diff --git a/index.html b/index.html index 0114aff1..23350d25 100644 --- a/index.html +++ b/index.html @@ -491,9 +491,18 @@

Syntax Tokens and Keywords

language of a JSON-LD document. This keyword is described in .
@type
-
Used to set the data type of a node or - typed value. This keyword is described in - .
+
Used to set the type of a node or the datatype of a typed value. + This keyword is described further in + and . +
The use of @type to define a type for both + node objects and value objects addresses the basic need to type data, + be it a literal value or a more complicated resource. + Experts may find the overloaded use of the @type keyword for both purposes concerning, + but should note that Web developer usage of this feature over multiple years + has not resulted in its misuse due to the far less frequent use of @type + to express typed literal values. +
+
@container
Used to set the default container type for a term. This keyword is described in the following sections: @@ -533,7 +542,7 @@

Syntax Tokens and Keywords

@nest
Collects a set of nested properties within a node object.
@none
Used as an index value - in an id map, language map, type map, or elsewhere where a dictionary is + in an index map, id map, language map, type map, or elsewhere where a dictionary is used to index into other values.
@prefix
With the value true, allows this term to be used to construct a compact IRI @@ -712,6 +721,11 @@

Basic Concepts

to work with for human developers. To address this issue, JSON-LD introduces the notion of a context as described in the next section.

+

This section only covers the most basic features of JSON-LD. More advanced features, + including typed values, indexed values, and named graphs, + can be found in .

+ +

The Context

@@ -1229,6 +1243,86 @@

Node Identifiers

+
+

Uses of JSON Objects

+

As a syntax, JSON has only a limited number of syntactic elements:

+ + +

The JSON-LD data model allows for a richer set of resources, based on the RDF data model. + The data model is described more fully in . + JSON-LD uses JSON objects to describe various resources, along with the relationships + between these resources:

+
+
Node objects
+ Node objects are used to define nodes in the linked data graph + which may have both incoming and outgoing edges. + Node objects are principle structure for defining resources having properties. + See for the normative definition. +
+
Value objects
+ Value objects are used for describing literal nodes in a linked data graph + which may have only incoming edges. + In JSON, some literal nodes may be described without the use of a JSON object + (e.g., numbers, strings, and boolean values), + but in the expanded form, + all literal nodes are described using value objects. + See for more information, + and for the normative definition. +
+
List Objects and Set objects
+
Map Objects
+ JSON-LD uses various forms of dictionaries as ways to more easily access values of a property. +
+
Language Maps
+ Allows mulitple values differing in their associated language to be + indexed by language tag. + See for more information, + and for the normative definition. +
+
Index Maps
+ Allows multiple values (node objects or value objects) to be indexed by an associated @index. + See for more information, + and for the normative definition. +
+
Id Maps
+ Allows multiple node objects to be indexed by an associated @id. + See for more information, + and for the normative definition. +
+
Type Maps
+ Allows multiple node objects to be indexed by an associated @type. + See for more information, + and for the normative definition. +
+
Named Graph Indexing
+ Allows multiple named graphs to be indexed by an associated graph name. + See for more information. +
+
+
+
Graph objects
+ A Graph object is much like a node object, except that it defines a named graph. + See for more information, + and for the normative definition. +
+
Context Definitions
+ A Context Definition uses the JSON object form, but is not itself data in a linked data graph. + A Context Definition also may contain expanded term definitions, + which are also represented using JSON objects. + See , + for more information, + and for the normative definition. +
+
+
+

Specifying the Type

@@ -1241,7 +1335,7 @@

Specifying the Type

type is a Person; making this explicit with @type helps to clarify the association.

-

The type of a particular node can be specified using 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.

@@ -1364,7 +1458,7 @@

Specifying the Type

-

The value of an @type key may also be a term defined in the active context:

+

The value of a @type key may also be a term defined in the active context:

-

This section only covers the most basic features associated with - types in JSON-LD. It is worth noting that the @type - keyword is not only used to specify the type of a - node but also to express typed values - (as described in ) and to - type coerce values (as described in - ). Specifically, @type - cannot be used in a context to define a node's - type. For a detailed description of the differences, please refer to - .

- +

In addition to setting the type of nodes, + @type can also be used to set the type of a value + to create a typed value. + This use of @type is similar to that used to define the type of a node object, + but value objects are restricted to having just a single type. + The use of @type to create typed values is discussed more fully in .

+ +

Typed values can also be defined implicitly, by specifying + @type in an expanded term definition. + This is covered more fully in .

+ +

The ability coerce a value using a term definition is distinct + from setting one or more types on a node object, as the former does not result in + new data being added to the graph, while the later manages node types + through adding additional relationships to the graph.

@@ -2579,7 +2677,7 @@

Using the Document Base as the Default Vocabulary

Since keywords cannot be redefined, they can also not be aliased to other keywords.

-

Aliased keywords may not be used within a context, itself.

+

Aliased keywords MUST NOT be used within a context, itself.

IRI Expansion within a Context

@@ -3025,7 +3123,7 @@

Using the Document Base as the Default Vocabulary

-

The modified key's value above is automatically type coerced to a +

The modified key's value above is automatically interpreted as a dateTime value because of the information specified in the @context. The example tabs show how a JSON-LD processor will interpret the data.

@@ -3102,7 +3200,8 @@

Using the Document Base as the Default Vocabulary

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.

+ a value type are different. + For more on adding types to nodes, see .

A node type specifies the type of thing that is being described, like a person, place, event, or web page. A @@ -9540,6 +9639,175 @@

Context Definitions

See for further discussion on contexts.

+
+

Keywords

+

JSON-LD keywords are described in , + this section describes where each keyword may appear within different JSON-LD structures.

+ +
+
@base
+ The @base keyword MUST NOT be aliased, and MAY be used as a key in a context definition. + Its value MUST be an absolute IRI, a relative IRI, or null. +
+
@container
+ The @container keyword MUST NOT be aliased, and MAY be used as a key in an expanded term definition. + 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. + The value may also be an array + containing @graph along with either @id or + @index and also optionally including @set. +
+
@context
+ The @context keyword MUST NOT be aliased, and MAY be used as a key in the following objects: + + The value of @context MUST be + null, + an absolute IRI, + a relative IRI, + a context definition, or + an array composed of any of these. +
+
@id
+ The @id keyword MAY be aliased and MAY be used as a key in a node object or a graph object. + The unaliased @id MAY be used as a key in an expanded term definition, + or as the value of the @container key within an expanded term definition. + The value of the @id key MUST be an absolute IRI, a relative IRI, + or a compact IRI (including blank node identifiers). + See , + , and + for further discussion on + @id values. +
+
@index
+ The @index keyword MAY be aliased and MAY be used as a key in a + node object, value object, graph object, set object, or list object. + The unaliased @index MAY be used as the value of the @container key within an expanded term definition. + Its value MUST be a string. + See for a further discussion. +
+
@language
+ The @language keyword MAY be aliased and MAY be used as a key in a value object. + The unaliased @language MAY be used as a key in a context definition, + or as the value of the @container key within an expanded term definition. + Its value MUST be a string with the lexical form described in [[BCP47]] or be null.. + See for a further discussion. +
+
@list
+ The @list keyword MAY be aliased and MUST be used as a key in a list object. + The unaliased @list MAY be used as the value of the @container key within an expanded term definition. + Its value MUST be one of the following: + + +

See for further discussion on sets and lists.

+
+
@nest
+ The @nest keyword MAY be aliased and MAY be used as a key in a node object. + The unaliased @nest MAY be used as the value of a simple term definition, + or as a key in an expanded term definition. + When used in a node object, its value must be a dictionary. + When used in an expanded term definition, its value MUST be a term expanding to @nest. + Its value MUST be a string. + See for a further discussion. +
+
@none
+ The @none keyword MAY be aliased and MAY beused as a key in an + index map, id map, language map, type map. + See , + , + , + , + , or + + for a further discussion.
+
@prefix
+ The @prefix keyword MUST NOT be aliased, and MAY be used as a key in an expanded term definition. + Its value MUST be true or false. + See + and + for a further discussion. +
+
@reverse
+ The @reverse keyword MAY be aliased and MAY be used as a key in a node object. + The unaliased @reverse MAY be used as a key in an expanded term definition. + The value of the @reverse key MUST be an absolute IRI, a relative IRI, + or a compact IRI (including blank node identifiers). + See and + for further discussion. +
+
@set
+ The @set keyword MAY be aliased and MUST be used as a key in a set object. + The unaliased @set MAY be used as the value of the @container key within an expanded term definition. + Its value MUST be one of the following: + + +

See for further discussion on sets and lists.

+
+
@type
+ The @type keyword MAY be aliased and MAY be used as a key in a node object or a value object. + The unaliased @type MAY be used as a key in an expanded term definition, + or as the value of the @container key within an expanded term definition. + The value of the @type key MUST be a term, absolute IRI, a relative IRI, + or a compact IRI (including blank node identifiers). + Within an expanded term definition, its value may also be either @id or @vocab. + This keyword is described further in + and . +
+
@value
+ The @value keyword MAY be aliased and MUST be used as a key in a value object. + Its value key MUST be either a string, a number, true, false or null. + This keyword is described further in . +
+
@version
+ The @version keyword MUST NOT be aliased and MAY be used as a key in a context definition. + Its value MUST be a number with the value 1.1. + This keyword is described further in . +
+
@vocab
+ The @vocab keyword MUST NOT be aliased and MAY be used as a key in a context definition + or as the value of @type in an expanded term definition. + Its value MUST be a absolute IRI, a compact IRI, a blank node identifier, an empty string (""), a term, or null. + This keyword is described further in , + and . +
+
+