From 79a72d05253db915967e7fb8e50cfec9701eef3d Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Mon, 18 Feb 2019 16:08:49 -0800 Subject: [PATCH 1/5] Add sub-sections to the compaction section to describe the effect of different term definitions on compaction. This includes describing `@type: @none`. For w3c/json-ld-api#33. --- Gemfile.lock | 2 +- index.html | 333 +++++++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 312 insertions(+), 23 deletions(-) diff --git a/Gemfile.lock b/Gemfile.lock index 3cea9e32..0bed29ea 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,6 +1,6 @@ GIT remote: git://github.com/ruby-rdf/json-ld.git - revision: 6bb0c2d269e8cf80152d519ee5fd16696812b1f2 + revision: 147930bfd2bceeef4d6f79f203cddc4134e3b65d branch: develop specs: json-ld (3.0.2) diff --git a/index.html b/index.html index e9c51fe6..c7801714 100644 --- a/index.html +++ b/index.html @@ -1861,8 +1861,8 @@

Advanced Concepts

The outer array is standard for a document in - expanded document form - and flattened document form, + expanded document form + and flattened document form, and may be necessary when describing a disconnected graph, where nodes may not reference each other. In such cases, using a top-level dictionary with a @graph property can be useful for saving @@ -8799,8 +8799,8 @@

Graph Containers

JSON-LD's media type defines a profile parameter which can be used to signal or request - expanded document form. The profile URI identifying expanded document - form is http://www.w3.org/ns/json-ld#expanded.

+ expanded document form. The profile URI identifying + expanded document form is http://www.w3.org/ns/json-ld#expanded.

Compacted Document Form

@@ -8857,7 +8857,7 @@

Graph Containers

against the JSON-LD input document provided above would result in the following output:

-

Flattened Document Form

@@ -8970,11 +9254,11 @@

Graph Containers

JSON-LD's media type defines a profile parameter which can be used to signal or request - flattened document form. The profile URI identifying flattened document - form is http://www.w3.org/ns/json-ld#flattened. It can be - combined with the profile URI identifying - expanded document form or - compacted document from.

+ flattened document form. The profile URI identifying + flattened document form is http://www.w3.org/ns/json-ld#flattened. + It can be combined with the profile URI identifying + expanded document form or + compacted document form.

Framed Document Form

@@ -9085,6 +9369,11 @@

Graph Containers

--> + +

JSON-LD's media type defines a + profile parameter which can be used to signal or request + framed document form. The profile URI identifying + framed document form is http://www.w3.org/ns/json-ld#framed.

@@ -10068,7 +10357,7 @@

Lists and Sets

of terms associated with an @set or @list container will always be represented in the form of an array when a document is processed—even if there is just a single value that would otherwise be optimized to - a non-array form in compact document form. + a non-array form in compacted document form. This simplifies post-processing of the data as the data is always in a deterministic form.

@@ -10289,7 +10578,7 @@

Context Definitions

If the expanded term definition contains the @type keyword, its value MUST be an absolute IRI, a compact IRI, a term, null, or one of the - keywords @id or @vocab.

+ keywords @id, @none, or @vocab.

If the expanded term definition contains the @language keyword, its value MUST have the lexical form described in [[BCP47]] or be null.

@@ -11056,13 +11345,13 @@

application/ld+json

This specification defines four values for the profile parameter.

http://www.w3.org/ns/json-ld#expanded
-
To request or specify expanded JSON-LD document form.
+
To request or specify expanded JSON-LD document form.
http://www.w3.org/ns/json-ld#compacted
-
To request or specify compacted JSON-LD document form.
+
To request or specify compacted JSON-LD document form.
http://www.w3.org/ns/json-ld#flattened
-
To request or specify flattened JSON-LD document form.
+
To request or specify flattened JSON-LD document form.
http://www.w3.org/ns/json-ld#framed
-
To request or specify framed JSON-LD document form.
+
To request or specify framed JSON-LD document form.

Other specifications may publish additional profile parameter URIs with their own defined sematics.

@@ -11161,7 +11450,7 @@

Examples

-->

Requests the server to return the requested resource as JSON-LD - in expanded document form.

+ in expanded document form.

Examples
     -->

Requests the server to return the requested resource as JSON-LD - in compacted document form. + in compacted document form. As no explicit context resource is specified, the server compacts using an application-specific default context.

@@ -11189,8 +11478,8 @@

Examples

-->

Requests the server to return the requested resource as JSON-LD - in both compacted document form - and flattened document form. + in both compacted document form + and flattened document form. Note that as whitespace is used to separate the two URIs, they are enclosed in double quotes (").

From fb326bc5628a729420860b5d2a4ed2e0e465461e Mon Sep 17 00:00:00 2001 From: Pierre-Antoine Champin Date: Tue, 19 Feb 2019 17:43:45 +0100 Subject: [PATCH 2/5] fixed 2 minor typos --- index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index c7801714..0c52dc78 100644 --- a/index.html +++ b/index.html @@ -8896,7 +8896,7 @@

Graph Containers

to authors creating contexts to be used for compacting JSON-LD documents.

The purpose of compaction is to apply the term definitions, vocabulary mapping, default language, and base IRI to an existing JSON-LD document to cause it to be represented in a form - that is taylored to the use of the JSON-LD document directly as JSON. + that is tailored to the use of the JSON-LD document directly as JSON. This includes representing values as strings, rather than value objects, where possible, shortening the use of list objects into simple arrays, reversing the relationship between nodes, and using data maps to index into multiple values instead of @@ -9004,7 +9004,7 @@

Graph Containers

and values using node objects and value objects. Moreover, property values are always contained within an array, even when there is only one value. Sometimes this is useful to maintain a uniformity of access, - but most JSON data uses the simplest possible representation, meaning that + but most JSON data use the simplest possible representation, meaning that properties have single values, which are represented as strings or as structured values such as node objects. By default, compaction will represent values which are simple strings as strings, From 7225b1debf9fbcb7daa78177fd8d1400f98e0e1e Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Tue, 19 Feb 2019 12:04:58 -0800 Subject: [PATCH 3/5] Address @iherman's comments. --- index.html | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/index.html b/index.html index 0c52dc78..ba8bef2f 100644 --- a/index.html +++ b/index.html @@ -9035,7 +9035,7 @@

Graph Containers

{"@value": "English", "@language": "en"} ], "http://example.com/iri": [ - {"@id": "http://example.org/iri"} + {"@id": "http://example.com/some-location"} ] }] --> @@ -9076,7 +9076,7 @@

Graph Containers

"plain": ["string", true, 1], "date": "2018-02-16", "en": "English", - "iri": "http://example.org/iri" + "iri": "http://example.com/some-location" } --> @@ -9117,7 +9117,7 @@

Graph Containers

{"@value": 1}, {"@value": 10.0}, {"@value": "plain"}, - {"@value": true, "@type": "http://www.w3.org/2001/XMLSchema#boolean"}, + {"@value": false, "@type": "http://www.w3.org/2001/XMLSchema#boolean"}, {"@value": "english", "@language": "en"}, {"@value": "2018-02-17", "@type": "http://www.w3.org/2001/XMLSchema#date"}, {"@id": "http://example.com/iri"} @@ -9139,9 +9139,7 @@

Graph Containers

-->

The compacted version will use string values for the defined terms - when the values match the term definition. Note that there is - no term defined for "plain", that is created automatically using - the vocabulary mapping. + when the values match the term definition. Also, the other native values, 1 and true, can be represented without defining a specific type mapping.

@@ -9163,7 +9161,7 @@

Graph Containers

{"@value": 1}, {"@value": 10.0}, {"@value": "plain"}, - {"@value": true, "@type": "xsd:boolean"}, + {"@value": false, "@type": "xsd:boolean"}, {"@value": "english", "@language": "en"}, {"@value": "2018-02-17", "@type": "xsd:date"}, {"@id": "http://example.com/iri"} From c95f372b88322a9c3a24a8785e10b6ca5360423a Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Tue, 19 Feb 2019 14:39:17 -0800 Subject: [PATCH 4/5] Add more sections describing the compaction algorithm for JSON-LD authors. --- index.html | 760 ++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 542 insertions(+), 218 deletions(-) diff --git a/index.html b/index.html index ba8bef2f..e6aeecc6 100644 --- a/index.html +++ b/index.html @@ -761,7 +761,7 @@

The Context

"name": "http://schema.org/name",**** ####↑ This means that 'name' is shorthand for 'http://schema.org/name'#### ****"image": { - "@id": "http://schema.org/image",**** + "@id": "http://schema.org/image",**** ####↑ This means that 'image' is shorthand for 'http://schema.org/image'#### ****"@type": "@id"**** ####↑ This means that a string value associated with 'image' @@ -5252,7 +5252,7 @@

Using the Document Base for the Default Vocabulary

class="sectionRef"> for a further discussion.

-

Using @set with @type

+

Using @set with @type

When processing mode is set to json-ld-1.1, @type may be used with an expanded term definition with @container set to @set; no other members may be set within such an expanded term definition. @@ -5270,7 +5270,7 @@

Using the Document Base for the Default Vocabulary

} --> - +
@@ -8916,87 +8916,87 @@

Graph Containers

i.e., used as a property, or a value of @type, or as the value of a term described as "@type": "@vocab".

- + --> + +

The compaction algorithm will shorten all vocabulary-relative IRIs that begin with http://schema.org/:

+ 
+      
+
+

Note that two IRIs were shortened, unnecessary arrays are removed, and simple string + values are replaced with the string.

+ - + --> + +

The compaction algorithm will shorten all document-relative IRIs that begin with http://example.com/:

+ 
+      
+
+

Representing Values as Strings

@@ -9015,87 +9015,268 @@

Graph Containers

of the term used as a property. See for more details.

- -
- -

Term Selection

-
- -

Representing Singular Values as Arrays

+ --> + +

The compacted version will use string values for the defined terms + when the values match the term definition. Note that there is + no term defined for "plain", that is created automatically using + the vocabulary mapping. + Also, the other native values, + 1 and true, + can be represented without defining a specific type mapping.

+ 
+      
+
+

Representing Lists as Arrays

+

As described in , + JSON-LD has an expanded syntax for representing ordered values, + using the @list keyword. + To simplify the representation in JSON-LD, a term can be defined with + "@container": "@list" which causes all values of a + property using such a term to be considered ordered.

+ +

Reversing Node Relationships

+

In some cases, the property used to relate two nodes may + be better expressed if the nodes have a reverse direction, + for example, when describing a relationship between + two people and a common parent. + See for more details.

+ + + +

Reverse properties can be even more useful when combined with + framing, which can actually make node objects defined + at the top-level of a document to become embedded nodes. + JSON-LD provides a means to index such values, by defining + an appropriate @container definition within a term definition.

Indexing Values

+

Properties with multiple values are typically represented using + an unordered array. This means that an application working + on an internalized representation of that JSON would need to + iterrate through the values of the array to find a value matching + a particular pattern, such as a language-tagged string + using that language en.

+ + + +

Data can be indexed on a number of different keys, including + @id, @type, @language, @index and more. + See and + for more details.

Normalizing Values as Objects

@@ -9105,71 +9286,214 @@

Graph Containers

This causes the Value Compaction algorithm to always use the object form of values, although components of that value may be compacted.

- + --> + +

The compacted version will use string values for the defined terms + when the values match the term definition. + Also, the other native values, + 1 and true, + can be represented without defining a specific type mapping.

+ 
+      
+
+ +
+ +

Representing Singular Values as Arrays

+

Generally, when compacting, properties having only one value are + represented as strings or dictionaries, while properties having + multiple values are represented as an array of strings or dictionaries. + This means that applications accessing such properties needs to be prepared + to accept either representation. To force all values to be represented + using an array, a term definition can set "@container": "@set". + Moreover, `@set` can be used in combination with other container settings, + for example looking at our language-map example from :

+ + +
+ +

Term Selection

+

When compacting, the Compaction algorithm will compact using a term + for a property only when the values of that property match the + @container, @type, and @language specifications for that term definition. + This can actually split values between different properties, all of which + have the same IRI. In case there is no matching term definition, + the compaction algorithm will compact using the absolute IRI of the property.

+ +
@@ -9690,7 +10014,7 @@

Graph Containers

Dynamic changes to base URLs.

-

Restrictions for contents of JSON-LD script elements

+

Restrictions for contents of JSON-LD script elements

Due to the HTML Restrictions for contents of <script> elements additional encoding restrictions are placed on JSON-LD data contained in script elements.

@@ -10982,9 +11306,9 @@

Description of the Linked Data Dataset figu
Alice
an RDF literal with no datatype or language.
weiblich | de
-
an language-tagged string with the value "weiblich" and language-tag "de".
+
an language-tagged string with the value "weiblich" and language tag "de".
female | en
-
an language-tagged string with the value "female" and language-tag "en".
+
an language-tagged string with the value "female" and language tag "en".

The second and third boxes describe two named graphs, with the graph names From 9c1cbccea9f1a886d07da37e60cdef6fec5fefed Mon Sep 17 00:00:00 2001 From: Pierre-Antoine Champin Date: Wed, 20 Feb 2019 19:38:11 +0100 Subject: [PATCH 5/5] fixed minor typos --- index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index e6aeecc6..c1d981b0 100644 --- a/index.html +++ b/index.html @@ -9357,10 +9357,10 @@

Graph Containers

Generally, when compacting, properties having only one value are represented as strings or dictionaries, while properties having multiple values are represented as an array of strings or dictionaries. - This means that applications accessing such properties needs to be prepared + This means that applications accessing such properties need to be prepared to accept either representation. To force all values to be represented using an array, a term definition can set "@container": "@set". - Moreover, `@set` can be used in combination with other container settings, + Moreover, @set can be used in combination with other container settings, for example looking at our language-map example from :