From 06586d78c482db8dd969c6cde27464d7d4b1297a Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Tue, 13 Nov 2018 15:39:11 -0800 Subject: [PATCH 1/5] Improved `@type` keyword definition, and added _Uses of JSON Objects_ section. --- index.html | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 92 insertions(+), 3 deletions(-) diff --git a/index.html b/index.html index 0114aff1..e553e026 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 notion of type can be confusing, as both + nodes and literal values can have types, + but in the data model, + these are fundamentally different things. + 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. +
+
@container
Used to set the default container type for a term. This keyword is described in the following sections: @@ -1431,6 +1440,86 @@

Specifying the Type

.

+ +
+

Uses of JSON Objects

+

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

+
    +
  • Numbers, which describe literal numeric values,
    • +
  • Strings, which may describe literal string values, or be used as the keys in a JSON object.
    • +
  • Boolean true and false, which describe literal boolean values,
    • +
  • Null, which describes the absense of a value,
    • +
  • Arrays, which describe an ordered set of values of any type, and
    • +
  • JSON objects, which provide a set of dictionary members, relating keys with values.
    • +
+ +

The JSON-LD data model allows for a richer set of resources, based on the RDF data mode. + 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. +
+
+
From 7656d4c47dd8fa6000680952e5e88e5493df3e18 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Wed, 14 Nov 2018 17:58:08 -0800 Subject: [PATCH 2/5] Add a section on keywords to the grammar, and slight improvement to type values. --- index.html | 178 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 174 insertions(+), 4 deletions(-) diff --git a/index.html b/index.html index e553e026..918a9c62 100644 --- a/index.html +++ b/index.html @@ -542,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 @@ -2668,7 +2668,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

@@ -3114,7 +3114,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 type 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.

@@ -3191,7 +3191,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 @@ -9629,6 +9630,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 . +
+
+
From 03e9c095ee53d768b9129c7a5a0b51664f08a106 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Thu, 15 Nov 2018 09:53:47 -0800 Subject: [PATCH 3/5] Suggestions from @msporny and HTML structural fixes. --- index.html | 50 +++++++++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/index.html b/index.html index 918a9c62..a391391c 100644 --- a/index.html +++ b/index.html @@ -494,13 +494,13 @@

Syntax Tokens and Keywords

Used to set the type of a node or the datatype of a typed value. This keyword is described further in and . -
The notion of type can be confusing, as both - nodes and literal values can have types, - but in the data model, - these are fundamentally different things. - 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. +
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
@@ -1453,7 +1453,7 @@

Uses of JSON Objects

  • JSON objects, which provide a set of dictionary members, relating keys with values.
    • -

    The JSON-LD data model allows for a richer set of resources, based on the RDF data mode. +

    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:

    @@ -3114,7 +3114,7 @@

    Using the Document Base as the Default Vocabulary

    -

    The modified key's value above is automatically type interpreted as 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.

    @@ -9643,24 +9643,24 @@

    Keywords

    @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. + @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 @context keyword MUST NOT be aliased, and MAY be used as a key in the following objects:
    • node objects (see ),
    • value objects (see ),
      • From e93776500afe71b947651753f2dfe3273ac85d60 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Thu, 15 Nov 2018 10:08:54 -0800 Subject: [PATCH 4/5] Move "Uses of JSON Objects" before "Specifying the Type" and add some discussion of setting the type on value objects, with references to "Typed Values" and "Type Coercion". --- index.html | 180 +++++++++++++++++++++++++++++------------------------ 1 file changed, 98 insertions(+), 82 deletions(-) diff --git a/index.html b/index.html index a391391c..9c103499 100644 --- a/index.html +++ b/index.html @@ -1238,6 +1238,86 @@

      Node Identifiers

    +
    +

    Uses of JSON Objects

    +

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

    +
      +
    • Numbers, which describe literal numeric values,
      • +
    • Strings, which may describe literal string values, or be used as the keys in a JSON object.
      • +
    • Boolean true and false, which describe literal boolean values,
      • +
    • Null, which describes the absense of a value,
      • +
    • Arrays, which describe an ordered set of values of any type, and
      • +
    • JSON objects, which provide a set of dictionary members, relating keys with values.
      • +
    + +

    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

    @@ -1250,7 +1330,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.

    @@ -1373,7 +1453,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:

    +

    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.

    +

    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 @@ -1440,86 +1536,6 @@

    Specifying the Type

    .

    - -
    -

    Uses of JSON Objects

    -

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

    -
      -
    • Numbers, which describe literal numeric values,
      • -
    • Strings, which may describe literal string values, or be used as the keys in a JSON object.
      • -
    • Boolean true and false, which describe literal boolean values,
      • -
    • Null, which describes the absense of a value,
      • -
    • Arrays, which describe an ordered set of values of any type, and
      • -
    • JSON objects, which provide a set of dictionary members, relating keys with values.
      • -
    - -

    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. -
    -
    -
    From a42ebb30a98b6b9d5d12ffae5a858b582d318057 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Sat, 17 Nov 2018 11:25:52 -0800 Subject: [PATCH 5/5] More note referencing Advanced Aoncepts to the end of the Basic Concepts introduction. --- index.html | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/index.html b/index.html index 9c103499..23350d25 100644 --- a/index.html +++ b/index.html @@ -721,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

    @@ -1523,18 +1528,6 @@

    Specifying the Type

    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.

    - -

    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 - .

    -