W3C home > Mailing lists > Public > public-annotation@w3.org > April 2016

Re: [web-annotation] HTML Serialization Use Cases

From: Tim Cole via GitHub <sysbot+gh@w3.org>
Date: Fri, 08 Apr 2016 03:53:33 +0000
To: public-annotation@w3.org
Message-ID: <issue_comment.created-207198440-1460087612-sysbot+gh@w3.org>
**## 3 Annotation Use Cases – 3 Serialization Options**

The JSON-LD 1.0 Specification in section 6.20 [1] says, "HTML script 
tags can be used to embed blocks of data in documents. This way, 
JSON-LD content can be easily embedded in HTML by placing it in a 
script element with the type attribute set to application/ld+json." 
(This section is non-normative.) Elsewhere, in appendices [2] [3]  
also non-normative, the specification does provide illustrations of 
how JSON-LD would transform to RDFa or Microdata; but importantly for 
us, the JSON-LD specification in the Microdata appendix says that, 
**"the JSON-LD representation of the Microdata information stays true 
to the desires of the Microdata community to avoid contexts and 
instead refer to items by their full IRI.**" (The same is effectively 
true for RDFa serializations.) Because our @context shortens some 
vocabulary items and hides the namespaces from which we borrow 
properties and classes, this means that developers choosing RDFa or 
Microdata to serialize annotations in HTML would need to use full 
property names and namespaces, e.g., oa:hasBody, oa:hasTarget, 
dcterms:creator. etc. 

For this reason, if we write a WG note regarding the serialization of 
annotations in HTML documents, we may want to recommend or highlight 
the approach of embedding JSON serializations of annotations in HTML 
as JSON-LD-in-script elements, rather than the use of RDFa or 
Microdata to serialize annotations. (Of course there could be 4th, 
5th, etc. option(s) -- e.g., extending HTML directly with new elements
 and/or attributes -- for serializing annotations in HTML that we 
might prefer to JSON-LD-in-script element – please suggest.)

I illustrate the approach of using JSON-LD-in-script elements in HTML 
to embed annotations [4] for the 3 HTML annotation use cases described
 below.  I also illustrate Microdata [5] and RDFa [6] options for the 
first use case, but only for the first use case, since I think it 
likely we will prefer JSON-LD-in-script or something else to RDFa or 

Finally, though this gets into issues of interface (not our 
bailiwick), to help illustrate the JSON-LD-in-script approach, I 
include in [4] some JavaScript that dynamically modifies the HTML 
based on the annotations that have been added to the HTML in script 
elements (e.g., adding anchors, tooltips, footnotes as appropriate).  
This code was written with Janina Sarol and is not meant to be 
generic, but is provided simply as proof-of-concept.

Use cases illustrated:

A.       Viewing an HTML blog entry about the birthday of Frances 
Scott Key [7], Tim wants to annotate the mention of the HMS Tonnant 
with a link to its Wikipedia page.  The target is the mention of the 
Tonnant in the HTML page and the body is the Wikipedia page 
(Resource). The annotation is embedded in the Web page in a script 
element with id='Anno1'. An HTML fragment (i.e., #Anno1) is then 
appended to the page URL to create the Annotation URI (is this 
acceptable practice? What are the identity requirements for 
annotations serialized in HTML?). 
B.      Viewing this same HTML blog entry, Tim wants to annotate the 
portrait of Key embedded in the HTML page with a Textual Body (noting 
that the portrait was painted many years after the death of its 
subject).  The target is a SpecificResource having the image as its 
source and the HTML Page URI as its scope. The script element id is 
'Anno2' and the Annotation URI is created in the same way.
C.      Viewing this same HTML blog entry, Tim wants to annotate the 
mention of the first publication of what became the US National Anthem
 with its full citation – essentially add a footnote. The TextualBody 
is the text of the citation, and the target is text in the HTML page. 
A second body, the link to the digitized article, is included. The 
script element containing the third annotation has attribute 

[1] https://www.w3.org/TR/json-ld/#embedding-json-ld-in-html-documents
[2] https://www.w3.org/TR/json-ld/#rdfa 
[3] https://www.w3.org/TR/json-ld/#microdata 

GitHub Notification of comment by tcole3
Please view or discuss this issue at 
 using your GitHub account
Received on Friday, 8 April 2016 03:53:34 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 18:54:45 UTC