From 516055299f803d547630f7f097ccebb3876b5a9b Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Sun, 23 Sep 2018 16:25:00 -0700 Subject: [PATCH 01/12] Update the JSON-LD in HTML section to be normative, describe dataset extraction, how to deal with multiple script elements and script element targeting using fragments. Fixes #23 and fixes #57. --- index.html | 307 +++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 287 insertions(+), 20 deletions(-) diff --git a/index.html b/index.html index 5b6d0540..4c078695 100644 --- a/index.html +++ b/index.html @@ -8329,41 +8329,308 @@

Graph Containers

ignored for such documents.

-

Embedding JSON-LD in HTML Documents

+

Embedding JSON-LD in HTML Documents

HTML script elements can be used to embed blocks of data in documents. This way, JSON-LD content can be easily embedded in HTML [[HTML52]] by placing it in a script element with the type attribute set to application/ld+json.

- 
-  
-
+

Depending on how the HTML document is served, certain strings may need - to be escaped.

+ to be escaped. See + + Restrictions for contents of script elements + in [[!HTML52]] for details. In particular, the content MAY be enclosed + in the HTML comment open (<!--) and comment close (-->) text sequences

+ +

Defining how such data may be used is beyond the scope of this specification. The embedded JSON-LD document might be extracted as is or, e.g., be interpreted as RDF.

-

If JSON-LD content is extracted as RDF [[RDF11-CONCEPTS]], it should be expanded into an +

If JSON-LD content is extracted as RDF [[RDF11-CONCEPTS]], it MUST be expanded into an RDF Dataset using the Deserialize JSON-LD to RDF Algorithm - [[JSON-LD11-API]].

+ [[JSON-LD11-API]]. All script elements + with type application/ld+json MUST be processed and merged + into a single dataset with equivalent blank node identifiers contained in + separate script elements treated as if they were in a single document (i.e., + blank nodes are shared between different JSON-LD script elements).

+ + + +

Otherwise, unless a specific script is targeted + (see ), + only the first script element of type application/ld+json is used.

+ +

When processing a JSON-LD + script element, + only the resolved document location of the + containing HTML document is used to establish the default base IRI of the enclosed + JSON-LD content.

+ +

Locating a Specific JSON-LD Script Element

+

A specific + script element + within an HTML document may be located using + a fragment identifier matching the unique identifier + of the script element within the HTML document located by a URL (see [[!DOM]]).

+

For example, given an HTML document located at http://example.com/document, + a script element identified by "schema" can be targeted using the URL + http://example.com/document#schema.

+ + +
From 96f5ea5e3b9443d77173cb86469ae69b6932cd55 Mon Sep 17 00:00:00 2001 From: BigBlueHat Date: Wed, 17 Oct 2018 10:32:09 -0700 Subject: [PATCH 02/12] Fix typo --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 4c078695..5a131fc0 100644 --- a/index.html +++ b/index.html @@ -8566,7 +8566,7 @@

Graph Containers

within an HTML document may be located using a fragment identifier matching the unique identifier of the script element within the HTML document located by a URL (see [[!DOM]]).

-

For example, given an HTML document located at http://example.com/document, +

For example, given an HTML document located at http://example.com/document, a script element identified by "schema" can be targeted using the URL http://example.com/document#schema.

From b4afae7d9d6fe91751aaf88352115b91828e5367 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Wed, 17 Oct 2018 10:54:20 -0700 Subject: [PATCH 03/12] Update HTML examples per comment. --- index.html | 48 +++++++++++++++++++++++++----------------------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/index.html b/index.html index 5a131fc0..465428f7 100644 --- a/index.html +++ b/index.html @@ -77,7 +77,7 @@ companyURL: "https://digitalbazaar.com/", note: "v1.0" }, { name: "Dave Longley", - url: "https://digitalbazaar.com/", + url: "https://digitalbazaar.com/author/dlongley/", company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/", note: "v1.0" }, @@ -8498,19 +8498,19 @@

Graph Containers
+ - + + -
SubjectPropertyValue
http://greggkellogg.net/foaf#merdf:typefoaf:Person
https://digitalbazaar.com/author/dlongley/rdf:typeschema:Person
https://digitalbazaar.com/author/dlongley/schema:nameDave Longley
http://greggkellogg.net/foaf#merdf:typeschema:Person
http://greggkellogg.net/foaf#mefoaf:nameGregg Kellogg
http://greggkellogg.net/foaf#meschema:nameGregg Kellogg
@@ -8540,11 +8541,12 @@

Graph Containers

data-result-for="Combining multiple JSON-LD script elements into a single dataset-original" data-to-rdf> @@ -8567,8 +8569,8 @@

Graph Containers

a fragment identifier matching the unique identifier of the script element within the HTML document located by a URL (see [[!DOM]]).

For example, given an HTML document located at http://example.com/document, - a script element identified by "schema" can be targeted using the URL - http://example.com/document#schema.

+ a script element identified by "name" can be targeted using the URL + http://example.com/document#name.

+ +

HTML allows for Dynamic changes to base URLs. + This specification does not require any specific behavior, + and to ensure that all systems process the base IRI equivalently, authors SHOULD + either use absolute IRIs, or explicitly as defined in . + Implementations (particularly those natively operating in the [[!DOM]]) MAY take into consideration + Dynamic changes to base URLs.

+

Locating a Specific JSON-LD Script Element

A specific script element diff --git a/yaml/Flattened-and-expanded-form-for-the-previous-example.yaml b/yaml/Flattened-and-expanded-form-for-the-previous-example.yaml index 4004cbea..eff79d14 100644 --- a/yaml/Flattened-and-expanded-form-for-the-previous-example.yaml +++ b/yaml/Flattened-and-expanded-form-for-the-previous-example.yaml @@ -1,4 +1,4 @@ -Example 108: Flattened and expanded form for the previous example +Example 109: Flattened and expanded form for the previous example --- - "@id": _:b0 http://xmlns.com/foaf/0.1/name: Dave Longley diff --git a/yaml/JSON-LD-using-native-data-types-for-numbers-and-boolean-values.yaml b/yaml/JSON-LD-using-native-data-types-for-numbers-and-boolean-values.yaml index 65e8f1cb..444da4b3 100644 --- a/yaml/JSON-LD-using-native-data-types-for-numbers-and-boolean-values.yaml +++ b/yaml/JSON-LD-using-native-data-types-for-numbers-and-boolean-values.yaml @@ -1,4 +1,4 @@ -Example 114: JSON-LD using native data types for numbers and boolean values +Example 115: JSON-LD using native data types for numbers and boolean values --- "@context": ex: http://example.com/vocab# diff --git a/yaml/Linked-Data-Dataset-compacted.yaml b/yaml/Linked-Data-Dataset-compacted.yaml index b3f0d9fa..045d99a7 100644 --- a/yaml/Linked-Data-Dataset-compacted.yaml +++ b/yaml/Linked-Data-Dataset-compacted.yaml @@ -1,4 +1,4 @@ -Example 106: Linked Data Dataset-compacted +Example 107: Linked Data Dataset-compacted --- "@context": - http://schema.org/ diff --git a/yaml/Linked-Data-Dataset-expanded.yaml b/yaml/Linked-Data-Dataset-expanded.yaml index 05e82d7f..01a6b1d6 100644 --- a/yaml/Linked-Data-Dataset-expanded.yaml +++ b/yaml/Linked-Data-Dataset-expanded.yaml @@ -1,4 +1,4 @@ -Example 106: Linked Data Dataset-expanded +Example 107: Linked Data Dataset-expanded --- - "@id": http://example.com/people/alice http://schema.org/name: diff --git a/yaml/Same-book-description-in-JSON-LD-avoiding-contexts-.yaml b/yaml/Same-book-description-in-JSON-LD-avoiding-contexts-.yaml index 0ee44e68..0343e21d 100644 --- a/yaml/Same-book-description-in-JSON-LD-avoiding-contexts-.yaml +++ b/yaml/Same-book-description-in-JSON-LD-avoiding-contexts-.yaml @@ -1,4 +1,4 @@ -Example 121: Same book description in JSON-LD (avoiding contexts) +Example 122: Same book description in JSON-LD (avoiding contexts) --- - "@id": http://purl.oreilly.com/works/45U8QJGZSQKDH8N "@type": http://purl.org/vocab/frbr/core#Work diff --git a/yaml/Same-description-in-JSON-LD-context-shared-among-node-objects-.yaml b/yaml/Same-description-in-JSON-LD-context-shared-among-node-objects-.yaml index 7aa5bed4..356cd35a 100644 --- a/yaml/Same-description-in-JSON-LD-context-shared-among-node-objects-.yaml +++ b/yaml/Same-description-in-JSON-LD-context-shared-among-node-objects-.yaml @@ -1,4 +1,4 @@ -Example 119: Same description in JSON-LD (context shared among node objects) +Example 120: Same description in JSON-LD (context shared among node objects) --- "@context": foaf: http://xmlns.com/foaf/0.1/ diff --git a/yaml/Same-embedding-example-in-JSON-LD.yaml b/yaml/Same-embedding-example-in-JSON-LD.yaml index 6ccd9f0d..afe96254 100644 --- a/yaml/Same-embedding-example-in-JSON-LD.yaml +++ b/yaml/Same-embedding-example-in-JSON-LD.yaml @@ -1,4 +1,4 @@ -Example 113: Same embedding example in JSON-LD +Example 114: Same embedding example in JSON-LD --- "@context": foaf: http://xmlns.com/foaf/0.1/ diff --git a/yaml/Same-example-with-a-list-of-values-in-JSON-LD.yaml b/yaml/Same-example-with-a-list-of-values-in-JSON-LD.yaml index a5ba0744..d6aa8677 100644 --- a/yaml/Same-example-with-a-list-of-values-in-JSON-LD.yaml +++ b/yaml/Same-example-with-a-list-of-values-in-JSON-LD.yaml @@ -1,4 +1,4 @@ -Example 117: Same example with a list of values in JSON-LD +Example 118: Same example with a list of values in JSON-LD --- "@context": foaf: http://xmlns.com/foaf/0.1/ diff --git a/yaml/Sample-JSON-LD-document.yaml b/yaml/Sample-JSON-LD-document.yaml index 9d68f325..b9c6a011 100644 --- a/yaml/Sample-JSON-LD-document.yaml +++ b/yaml/Sample-JSON-LD-document.yaml @@ -1,4 +1,4 @@ -Example 107: Sample JSON-LD document +Example 108: Sample JSON-LD document --- "@context": name: http://xmlns.com/foaf/0.1/name diff --git a/yaml/The-same-set-of-statements-serialized-in-JSON-LD.yaml b/yaml/The-same-set-of-statements-serialized-in-JSON-LD.yaml index a6832a50..42f6d035 100644 --- a/yaml/The-same-set-of-statements-serialized-in-JSON-LD.yaml +++ b/yaml/The-same-set-of-statements-serialized-in-JSON-LD.yaml @@ -1,4 +1,4 @@ -Example 111: The same set of statements serialized in JSON-LD +Example 112: The same set of statements serialized in JSON-LD --- "@context": foaf: http://xmlns.com/foaf/0.1/ diff --git a/yaml/Using-the-document-base-URL-to-establish-the-default-base-IRI-expanded.yaml b/yaml/Using-the-document-base-URL-to-establish-the-default-base-IRI-expanded.yaml new file mode 100644 index 00000000..978ecb75 --- /dev/null +++ b/yaml/Using-the-document-base-URL-to-establish-the-default-base-IRI-expanded.yaml @@ -0,0 +1,10 @@ +Example 104: Using the document base URL to establish the default base IRI-expanded +--- +- "@id": http://dbpedia.org/resource/John_Lennon + http://xmlns.com/foaf/0.1/name: + - "@value": John Lennon + http://schema.org/birthDate: + - "@value": '1940-10-09' + "@type": http://www.w3.org/2001/XMLSchema#date + http://schema.org/spouse: + - "@id": http://dbpedia.org/resource/Cynthia_Lennon From 9f2ef5231ab64313e7acd2544d1db2e79ed30a8e Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Wed, 7 Nov 2018 14:18:21 -0800 Subject: [PATCH 06/12] Remove bits about resolving to HTML base element to be added in a separate PR for #23. --- ...blish-the-default-base-IRI-expanded.jsonld | 10 --- ...tablish-the-default-base-IRI-original.html | 9 -- ...lish-the-default-base-IRI-statements.table | 28 ------ ...-establish-the-default-base-IRI-turtle.ttl | 7 -- index.html | 86 +------------------ ...xpanded-form-for-the-previous-example.yaml | 2 +- ...-types-for-numbers-and-boolean-values.yaml | 2 +- yaml/Linked-Data-Dataset-compacted.yaml | 2 +- yaml/Linked-Data-Dataset-expanded.yaml | 2 +- ...ription-in-JSON-LD-avoiding-contexts-.yaml | 2 +- ...LD-context-shared-among-node-objects-.yaml | 2 +- yaml/Same-embedding-example-in-JSON-LD.yaml | 2 +- ...mple-with-a-list-of-values-in-JSON-LD.yaml | 2 +- yaml/Sample-JSON-LD-document.yaml | 2 +- ...t-of-statements-serialized-in-JSON-LD.yaml | 2 +- ...tablish-the-default-base-IRI-expanded.yaml | 10 --- 16 files changed, 12 insertions(+), 158 deletions(-) delete mode 100644 examples/Using-the-document-base-URL-to-establish-the-default-base-IRI-expanded.jsonld delete mode 100644 examples/Using-the-document-base-URL-to-establish-the-default-base-IRI-original.html delete mode 100644 examples/Using-the-document-base-URL-to-establish-the-default-base-IRI-statements.table delete mode 100644 examples/Using-the-document-base-URL-to-establish-the-default-base-IRI-turtle.ttl delete mode 100644 yaml/Using-the-document-base-URL-to-establish-the-default-base-IRI-expanded.yaml diff --git a/examples/Using-the-document-base-URL-to-establish-the-default-base-IRI-expanded.jsonld b/examples/Using-the-document-base-URL-to-establish-the-default-base-IRI-expanded.jsonld deleted file mode 100644 index 9fabe3e7..00000000 --- a/examples/Using-the-document-base-URL-to-establish-the-default-base-IRI-expanded.jsonld +++ /dev/null @@ -1,10 +0,0 @@ -[{ - "@id": "http://dbpedia.org/resource/John_Lennon", - "http://xmlns.com/foaf/0.1/name": [{"@value": "John Lennon"}], - "http://schema.org/birthDate": [ - {"@value": "1940-10-09", "@type": "http://www.w3.org/2001/XMLSchema#date"} - ], - "http://schema.org/spouse": [ - {"@id": "http://dbpedia.org/resource/Cynthia_Lennon"} - ] -}] \ No newline at end of file diff --git a/examples/Using-the-document-base-URL-to-establish-the-default-base-IRI-original.html b/examples/Using-the-document-base-URL-to-establish-the-default-base-IRI-original.html deleted file mode 100644 index a63d70d5..00000000 --- a/examples/Using-the-document-base-URL-to-establish-the-default-base-IRI-original.html +++ /dev/null @@ -1,9 +0,0 @@ - - { - "@context": "https://json-ld.org/contexts/person.jsonld", - "@id": "John_Lennon", - "name": "John Lennon", - "born": "1940-10-09", - "spouse": "Cynthia_Lennon" - } - \ No newline at end of file diff --git a/examples/Using-the-document-base-URL-to-establish-the-default-base-IRI-statements.table b/examples/Using-the-document-base-URL-to-establish-the-default-base-IRI-statements.table deleted file mode 100644 index d1563d25..00000000 --- a/examples/Using-the-document-base-URL-to-establish-the-default-base-IRI-statements.table +++ /dev/null @@ -1,28 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - -
SubjectPropertyValueValue Type
http://dbpedia.org/resource/John_Lennonfoaf:nameJohn Lennon 
http://dbpedia.org/resource/John_Lennonschema:birthDate1940-10-09xsd:date
http://dbpedia.org/resource/John_Lennonschema:spousehttp://dbpedia.org/resource/Cynthia_Lennon 
\ No newline at end of file diff --git a/examples/Using-the-document-base-URL-to-establish-the-default-base-IRI-turtle.ttl b/examples/Using-the-document-base-URL-to-establish-the-default-base-IRI-turtle.ttl deleted file mode 100644 index 80027b2f..00000000 --- a/examples/Using-the-document-base-URL-to-establish-the-default-base-IRI-turtle.ttl +++ /dev/null @@ -1,7 +0,0 @@ -@base . -@prefix foaf: . -@prefix schema: . -@prefix xsd: . - foaf:name "John Lennon"; - schema:birthDate "1940-10-09"^^xsd:date; - schema:spouse . \ No newline at end of file diff --git a/index.html b/index.html index 2b69feef..86dae4db 100644 --- a/index.html +++ b/index.html @@ -8560,92 +8560,10 @@

Graph Containers

When processing a JSON-LD script element, - the Document Base URL - of the containing HTML document, - as defined in [[HTML52]], - is used to establish the default base IRI of the enclosed + only the resolved document location of the + containing HTML document is used to establish the default base IRI of the enclosed JSON-LD content.

- - -

HTML allows for Dynamic changes to base URLs. - This specification does not require any specific behavior, - and to ensure that all systems process the base IRI equivalently, authors SHOULD - either use absolute IRIs, or explicitly as defined in . - Implementations (particularly those natively operating in the [[!DOM]]) MAY take into consideration - Dynamic changes to base URLs.

-

Locating a Specific JSON-LD Script Element

A specific script element diff --git a/yaml/Flattened-and-expanded-form-for-the-previous-example.yaml b/yaml/Flattened-and-expanded-form-for-the-previous-example.yaml index eff79d14..4004cbea 100644 --- a/yaml/Flattened-and-expanded-form-for-the-previous-example.yaml +++ b/yaml/Flattened-and-expanded-form-for-the-previous-example.yaml @@ -1,4 +1,4 @@ -Example 109: Flattened and expanded form for the previous example +Example 108: Flattened and expanded form for the previous example --- - "@id": _:b0 http://xmlns.com/foaf/0.1/name: Dave Longley diff --git a/yaml/JSON-LD-using-native-data-types-for-numbers-and-boolean-values.yaml b/yaml/JSON-LD-using-native-data-types-for-numbers-and-boolean-values.yaml index 444da4b3..65e8f1cb 100644 --- a/yaml/JSON-LD-using-native-data-types-for-numbers-and-boolean-values.yaml +++ b/yaml/JSON-LD-using-native-data-types-for-numbers-and-boolean-values.yaml @@ -1,4 +1,4 @@ -Example 115: JSON-LD using native data types for numbers and boolean values +Example 114: JSON-LD using native data types for numbers and boolean values --- "@context": ex: http://example.com/vocab# diff --git a/yaml/Linked-Data-Dataset-compacted.yaml b/yaml/Linked-Data-Dataset-compacted.yaml index 045d99a7..b3f0d9fa 100644 --- a/yaml/Linked-Data-Dataset-compacted.yaml +++ b/yaml/Linked-Data-Dataset-compacted.yaml @@ -1,4 +1,4 @@ -Example 107: Linked Data Dataset-compacted +Example 106: Linked Data Dataset-compacted --- "@context": - http://schema.org/ diff --git a/yaml/Linked-Data-Dataset-expanded.yaml b/yaml/Linked-Data-Dataset-expanded.yaml index 01a6b1d6..05e82d7f 100644 --- a/yaml/Linked-Data-Dataset-expanded.yaml +++ b/yaml/Linked-Data-Dataset-expanded.yaml @@ -1,4 +1,4 @@ -Example 107: Linked Data Dataset-expanded +Example 106: Linked Data Dataset-expanded --- - "@id": http://example.com/people/alice http://schema.org/name: diff --git a/yaml/Same-book-description-in-JSON-LD-avoiding-contexts-.yaml b/yaml/Same-book-description-in-JSON-LD-avoiding-contexts-.yaml index 0343e21d..0ee44e68 100644 --- a/yaml/Same-book-description-in-JSON-LD-avoiding-contexts-.yaml +++ b/yaml/Same-book-description-in-JSON-LD-avoiding-contexts-.yaml @@ -1,4 +1,4 @@ -Example 122: Same book description in JSON-LD (avoiding contexts) +Example 121: Same book description in JSON-LD (avoiding contexts) --- - "@id": http://purl.oreilly.com/works/45U8QJGZSQKDH8N "@type": http://purl.org/vocab/frbr/core#Work diff --git a/yaml/Same-description-in-JSON-LD-context-shared-among-node-objects-.yaml b/yaml/Same-description-in-JSON-LD-context-shared-among-node-objects-.yaml index 356cd35a..7aa5bed4 100644 --- a/yaml/Same-description-in-JSON-LD-context-shared-among-node-objects-.yaml +++ b/yaml/Same-description-in-JSON-LD-context-shared-among-node-objects-.yaml @@ -1,4 +1,4 @@ -Example 120: Same description in JSON-LD (context shared among node objects) +Example 119: Same description in JSON-LD (context shared among node objects) --- "@context": foaf: http://xmlns.com/foaf/0.1/ diff --git a/yaml/Same-embedding-example-in-JSON-LD.yaml b/yaml/Same-embedding-example-in-JSON-LD.yaml index afe96254..6ccd9f0d 100644 --- a/yaml/Same-embedding-example-in-JSON-LD.yaml +++ b/yaml/Same-embedding-example-in-JSON-LD.yaml @@ -1,4 +1,4 @@ -Example 114: Same embedding example in JSON-LD +Example 113: Same embedding example in JSON-LD --- "@context": foaf: http://xmlns.com/foaf/0.1/ diff --git a/yaml/Same-example-with-a-list-of-values-in-JSON-LD.yaml b/yaml/Same-example-with-a-list-of-values-in-JSON-LD.yaml index d6aa8677..a5ba0744 100644 --- a/yaml/Same-example-with-a-list-of-values-in-JSON-LD.yaml +++ b/yaml/Same-example-with-a-list-of-values-in-JSON-LD.yaml @@ -1,4 +1,4 @@ -Example 118: Same example with a list of values in JSON-LD +Example 117: Same example with a list of values in JSON-LD --- "@context": foaf: http://xmlns.com/foaf/0.1/ diff --git a/yaml/Sample-JSON-LD-document.yaml b/yaml/Sample-JSON-LD-document.yaml index b9c6a011..9d68f325 100644 --- a/yaml/Sample-JSON-LD-document.yaml +++ b/yaml/Sample-JSON-LD-document.yaml @@ -1,4 +1,4 @@ -Example 108: Sample JSON-LD document +Example 107: Sample JSON-LD document --- "@context": name: http://xmlns.com/foaf/0.1/name diff --git a/yaml/The-same-set-of-statements-serialized-in-JSON-LD.yaml b/yaml/The-same-set-of-statements-serialized-in-JSON-LD.yaml index 42f6d035..a6832a50 100644 --- a/yaml/The-same-set-of-statements-serialized-in-JSON-LD.yaml +++ b/yaml/The-same-set-of-statements-serialized-in-JSON-LD.yaml @@ -1,4 +1,4 @@ -Example 112: The same set of statements serialized in JSON-LD +Example 111: The same set of statements serialized in JSON-LD --- "@context": foaf: http://xmlns.com/foaf/0.1/ diff --git a/yaml/Using-the-document-base-URL-to-establish-the-default-base-IRI-expanded.yaml b/yaml/Using-the-document-base-URL-to-establish-the-default-base-IRI-expanded.yaml deleted file mode 100644 index 978ecb75..00000000 --- a/yaml/Using-the-document-base-URL-to-establish-the-default-base-IRI-expanded.yaml +++ /dev/null @@ -1,10 +0,0 @@ -Example 104: Using the document base URL to establish the default base IRI-expanded ---- -- "@id": http://dbpedia.org/resource/John_Lennon - http://xmlns.com/foaf/0.1/name: - - "@value": John Lennon - http://schema.org/birthDate: - - "@value": '1940-10-09' - "@type": http://www.w3.org/2001/XMLSchema#date - http://schema.org/spouse: - - "@id": http://dbpedia.org/resource/Cynthia_Lennon From 87ab2ee5f742b9f4f2a94cf5163a569351591498 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Wed, 7 Nov 2018 16:41:41 -0800 Subject: [PATCH 07/12] Add section on restrictions for JSON-LD script elements, which is more restrictive than the base HTML definitions. This includes a sketch processing model for removing comments and unescaping the resulting content. --- ...-LD-in-HTML-with-comments-statements.table | 14 +- index.html | 177 ++++++++++-------- ...SON-LD-in-HTML-with-comments-expanded.yaml | 2 +- 3 files changed, 111 insertions(+), 82 deletions(-) diff --git a/examples/Embedding-JSON-LD-in-HTML-with-comments-statements.table b/examples/Embedding-JSON-LD-in-HTML-with-comments-statements.table index 885958e7..6c6a21bc 100644 --- a/examples/Embedding-JSON-LD-in-HTML-with-comments-statements.table +++ b/examples/Embedding-JSON-LD-in-HTML-with-comments-statements.table @@ -1,28 +1,28 @@ - + - - + + - + - + - -
Subject Property Value Value Type
http://dbpedia.org/resource/John_Lennon foaf:name John Lennon  
http://dbpedia.org/resource/John_Lennon schema:birthDate 1940-10-09 xsd:date
http://dbpedia.org/resource/John_Lennon schema:spouse http://dbpedia.org/resource/Cynthia_Lennon  
\ No newline at end of file + + \ No newline at end of file diff --git a/index.html b/index.html index 86dae4db..2d9415bd 100644 --- a/index.html +++ b/index.html @@ -8401,80 +8401,6 @@

Graph Containers

-

Depending on how the HTML document is served, certain strings may need - to be escaped. See - - Restrictions for contents of script elements - in [[!HTML52]] for details. In particular, the content MAY be enclosed - in the HTML comment open (<!--) and comment close (-->) text sequences

- - -

Defining how such data may be used is beyond the scope of this specification. The embedded JSON-LD document might be extracted as is or, e.g., be interpreted as RDF.

@@ -8564,6 +8490,109 @@

Graph Containers

containing HTML document is used to establish the default base IRI of the enclosed JSON-LD content.

+

Restrictions for contents of JSON-LD script elements

+ +

Depending on how the HTML document is served, certain strings may need + to be escaped. In particular, the content MAY be enclosed + in the HTML comment-open (<!--) and comment-close (-->) text sequences.

+

As described in HTML Restrictions for contents of <script> elements + the textContent of a script element may include balanced comments + and other text which complicate extracting the JSON-LD content from a data blocks. + JSON-LD places further restrictions on the contents of + script elements containing JSON-LD.

+

A JSON-LD script element MAY begin with an optional comment-open surrounded by any amount of white space, + followed by valid JSON and ending with an optional comment-close surrounded by any amount of white space. + Any content within the JSON content which can be confused with a comment-open, script-open, + comment-close, or script-close MUST be escaped using a REVERSE SOLIDUS (\) character + as follows:

+
    +
  • <!-- → <\!--
    • +
  • <script → <\script
    • +
  • --> → --\>
    • +
  • </script → <\/script
    • +
+

Additionally, content of a script element MAY be escaped using HTML Character references, such as the following:

+
    +
  • &amp; → & (ampersand, U+0026)
    • +
  • &lt; → < (less-than sign, U+003C)
    • +
  • &gt; → > (greater-than sign, U+003E)
    • +
  • &quot; → " (quotation mark, U+0022)
    • +
  • &apos; → ' (apostrophe, U+0027)
    • +
+

JSON-LD Processors MUST remove surrounding comment-open and comment-close + sequences, unescape any escaped comment-open, comment-close, + script-open, and script-close sequences, + and turn HTML Character references into the corresponding Unicode. +

+ + +
+

Locating a Specific JSON-LD Script Element

A specific script element diff --git a/yaml/Embedding-JSON-LD-in-HTML-with-comments-expanded.yaml b/yaml/Embedding-JSON-LD-in-HTML-with-comments-expanded.yaml index 942fde73..5aa85067 100644 --- a/yaml/Embedding-JSON-LD-in-HTML-with-comments-expanded.yaml +++ b/yaml/Embedding-JSON-LD-in-HTML-with-comments-expanded.yaml @@ -1,4 +1,4 @@ -Example 102: Embedding JSON-LD in HTML with comments-expanded +Example 103: Embedding JSON-LD in HTML with comments-expanded --- - "@id": http://dbpedia.org/resource/John_Lennon http://xmlns.com/foaf/0.1/name: From 557ea4402c613bb86a7911652e5c953f74f3f32b Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Thu, 8 Nov 2018 16:32:35 -0800 Subject: [PATCH 08/12] Use reference to `space characters` instead of undefined "white space". --- index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index 2d9415bd..236c44ee 100644 --- a/index.html +++ b/index.html @@ -8500,8 +8500,8 @@

Graph Containers

and other text which complicate extracting the JSON-LD content from a data blocks. JSON-LD places further restrictions on the contents of script elements containing JSON-LD.

-

A JSON-LD script element MAY begin with an optional comment-open surrounded by any amount of white space, - followed by valid JSON and ending with an optional comment-close surrounded by any amount of white space. +

A JSON-LD script element MAY begin with an optional comment-open surrounded by any amount of space characters, + followed by valid JSON and ending with an optional comment-close surrounded by any amount of space characters. Any content within the JSON content which can be confused with a comment-open, script-open, comment-close, or script-close MUST be escaped using a REVERSE SOLIDUS (\) character as follows:

From 55120d6dd0d904bc1d9bb32f3ecd050c107361b2 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Sun, 11 Nov 2018 17:28:37 -0800 Subject: [PATCH 09/12] Update replacement for comments that should remain in the output. --- common/common.js | 4 ++-- index.html | 5 ++--- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/common/common.js b/common/common.js index b9e93ab1..14be9d70 100644 --- a/common/common.js +++ b/common/common.js @@ -271,6 +271,6 @@ function unComment(doc, content) { return content .replace(//, '') - .replace(/< !--/g, ''); + .replace(/< !\s*-\s*-/g, ''); } diff --git a/index.html b/index.html index 236c44ee..5d4e7fdc 100644 --- a/index.html +++ b/index.html @@ -8451,7 +8451,6 @@

Graph Containers

--> - @@ -8537,7 +8536,7 @@

Graph Containers

data-content-type="text/html"> From 472285ada7f18dfb78ead0a761a640c9260e8324 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Sun, 11 Nov 2018 17:46:57 -0800 Subject: [PATCH 10/12] More work at undoing comments that should be viewable in the HTML when extracting examples. --- common/extract-examples.rb | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/common/extract-examples.rb b/common/extract-examples.rb index cf8ebc97..5035f657 100755 --- a/common/extract-examples.rb +++ b/common/extract-examples.rb @@ -329,8 +329,8 @@ def save_example(examples:, element:, title:, example_number:, error:, warn:) # Remove (faked) XML comments and unescape sequences content = script_content .inner_html - .sub(/^\s*< !--/, '') - .sub(/-- >\s*$/, '') + .sub(/^\s*< !\s*-\s*-/, '') + .sub(/-\s*- >\s*$/, '') .gsub(/</, '<') end @@ -443,7 +443,10 @@ def save_example(examples:, element:, title:, example_number:, error:, warn:) # Set argument to referenced content to be parsed args[0] = if examples[ex[:result_for]][:ext] == 'html' && method == :expand # If we are expanding, and the reference is HTML, find the first script element. - doc = Nokogiri::HTML.parse(examples[ex[:result_for]][:content]) + doc = Nokogiri::HTML.parse( + examples[ex[:result_for]][:content] + .sub(/^\s*< !\s*-\s*-/, '') + .sub(/-\s*- >\s*$/, '')) # Get base from document, if present html_base = doc.at_xpath('/html/head/base/@href') @@ -457,12 +460,13 @@ def save_example(examples:, element:, title:, example_number:, error:, warn:) end StringIO.new(script_content .inner_html - .sub(/^\s*< !--/, '') - .sub(/-- >\s*$/, '') .gsub(/</, '<')) elsif examples[ex[:result_for]][:ext] == 'html' && ex[:target] # Only use the targeted script - doc = Nokogiri::HTML.parse(examples[ex[:result_for]][:content]) + doc = Nokogiri::HTML.parse( + examples[ex[:result_for]][:content] + .sub(/^\s*< !\s*-\s*-/, '') + .sub(/-\s*- >\s*$/, '')) script_content = doc.at_xpath(xpath) unless script_content errors << "Example #{ex[:number]} at line #{ex[:line]} references example #{ex[:result_for].inspect} with no JSON-LD script element" @@ -471,8 +475,6 @@ def save_example(examples:, element:, title:, example_number:, error:, warn:) end StringIO.new(script_content .to_html - .sub(/^\s*< !--/, '') - .sub(/-- >\s*$/, '') .gsub(/</, '<')) else StringIO.new(examples[ex[:result_for]][:content]) From 00c6ec62dd5ba5dae306bfd8664334ed713ff977 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Fri, 16 Nov 2018 10:43:30 -0800 Subject: [PATCH 11/12] Add at-risk note on commenting/escaping contents of HTML script tags. --- index.html | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/index.html b/index.html index 5d4e7fdc..593e9d4e 100644 --- a/index.html +++ b/index.html @@ -8490,6 +8490,10 @@

Graph Containers

JSON-LD content.

Restrictions for contents of JSON-LD script elements

+

As HTML entities and comments are not allowable in + JSON, the use of comments, escapes, + and HTML Character references + is subject to further discussion in the Working Group.

Depending on how the HTML document is served, certain strings may need to be escaped. In particular, the content MAY be enclosed From e7ae46fa7443fbdbed40cba982da5fb401997411 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Fri, 16 Nov 2018 10:43:38 -0800 Subject: [PATCH 12/12] Update issue list. --- index.html | 24 +++++++++--------------- 1 file changed, 9 insertions(+), 15 deletions(-) diff --git a/index.html b/index.html index 593e9d4e..fa4f4b26 100644 --- a/index.html +++ b/index.html @@ -10098,18 +10098,12 @@

Security Considerations

Open Issues

The following is a list of issues open at the time of publication.

Consider using "@type": "@json" to describe native values in the compact form.

-

Allows a term definition to include an @values block to describe structured values, such as for GeoJSON.

When requesting JSON-LD from an HTTP endpoint, it would be useful to provide a reference to a context or frame which should be used by the server to put the results into the proper format.

Provide a means for refering to a remote context without without requiring it to be downloaded.

-

Consider a container type, similar to @list for encoding things like schema:ItemList serializations, when the values are schema:ListItem and order is set through schema:position.

-

Consider the opposite of "@container": "@set"; this would be when there is exactly one entry in an @list, instead of compacting to an array, compact to a single item.

-

It would be useful if JSON-LD recognized both value (rdf:nil) and list ([]).

Consider a mechanism such as Microdata's @itemref for including objects within another referencing node.

Mechinism to allow freezing terms so that additional contexts don't override them.

Should consider html>head>base@href and xml:base, as appropriate.

Update terminology in the spec from IRI to URL.

-

For every example, there should be an equivalent of the example in the expanded form, in a table with the triples, in [[Turtle]] (as close to the JSON-LD structure as possible) and, possibly, as graphs. Not all of them would appear on the screen at the same time but, rather, the reader could choose what to see with some tabs.

-

Proposal is to start from scratch, ie, deprecating @graph and replacing the functionality with something cleaner.

    @@ -10119,16 +10113,16 @@

    Open Issues

  • Extend the @version keyword to take an array, where you can specify experimental extensions. For example: "@version": [1.1, "amazingExtensionFoo", "nicheExtensionBar"] - processors throw if they don't understand every extension listed.
-

Ensure that the output is consistent in shape. Thus if there can ever be multiple values, the structure is always an array.

-

-

-

-

+

Consider documentation best practices.

Consider issues surrounding confusion of differing expansion rules for @id, @type, and dictionary members.

-

Require JSON-LD processors to be able to identify and extract JSON-LD from a script tag with type application/ld+json within an HTML document.

-

- Instead of normatively requiring an initial context, such as RDFa does, instead JSON-LD has the ability to import contexts. This approach means that the existing context rules are followed, and the best practice context can be updated over time as new norms emerge in the community. If the best practice context is not useful to a particular community, then they don't need to import it. -

+

+

+

+

Node Types in @context.

+

+

+

+