Warning:
This wiki has been archived and is now read-only.
Serializations
The Open Annotation data model defines an abstract model, which is adaptable to different representations, such as HTML, JSON, and RDF/turtle. This contributes to interchange and interoperability by allowing flexibility to annotation authoring, aggregation, and display tools, in a variety of environments.
Contents
HTML
For a large number of use cases, the consumer of an annotation will see it in HTML, in the form of footnotes, comments, or proper annotations (like the Annotator sidebar or stickynotes); in many of these cases, the annotation will even be stored as HTML, or a some intermediate format like markdown that is predictably transformable into HTML, rather than in an abstracted form like RDF or JSON or even normalized SQL.
Many annotations will be only accessible as HTML, even through a service's API; think of Twitter, which will let you embed a tweet on a page by hitting their API and getting back the HTML snippet.
In order for an annotation system to consume, aggregate, and catalog those annotations, we want to provide clear guidance for how developers of annotation-producing software (e.g., microblogs, commenting systems, annotation libraries, and so on) can make markup that can be explicitly consumed as conforming to the OA data model.
RDFa
Here is a strawman for representing an annotation in HTML5+RDFa:
Corrected for Paolo's note: The following code now uses cnt:chars as currently recommended by the specs, rather than rdf:value.
<aside vocab="http://www.w3.org/ns/oa#" prefix="cnt: http://www.w3.org/2011/content#" typeof="Annotation">
<p>
<a property="annotatedBy" href="http://example.com/people/shepazu" typeof="foaf:Person">
<span property="foaf:name">Shepazu</span>
</a>
</p>
<time property="annotatedAt" datetime="2014-01-14T01:28:22-0500">
<a href="http://example.com/annotations/shepazu-1389680902"
title="1:28 AM - 14 Jan 2014">A few minutes ago</a>
</time>
<blockquote property="hasTarget"
resource="http://example.com/sourcedoc.html"
cite="http://example.com/sourcedoc.html"
data-prefix="essential feature of the memex. "
data-suffix=" When the user is building a tra" typeof="">
<p>The process of tying two items together is the important thing.</p>
<footer>
- <cite>
<a href="http://en.wikipedia.org/wiki/Vannevar_Bush">
<span>Vannevar Bush</span>
</a>
</cite>
</footer>
</blockquote>
<p property="hasBody" typeof="dctypes:Text"><span property="cnt:chars">Annotations are at the Web's core.</span></p>
<ul property="hasBody" typeof="Tag">
<li property="cnt:chars">annotations</li>
<li property="cnt:chars">web</li>
<li property="cnt:chars">standards</li>
</ul>
</aside>
Benjamin Young (talk) 19:42, 15 October 2014 (UTC) The use of <p> for containing the body means that the body cannot (in this case, at least) include any additional markup--thus limiting it to plain text. More examples including various format options are needed, and perhaps recommending a default "hasBody" container to something less typographic (div or section) would prepare for other body types beyond plain text. The <ul> for the Tag example seems correct, however.
<note> Element Proposal
A radically simplified version might include a new HTML element, <note>, which could be used for annotations, comments, and footnotes. This could have the benefit of an API, as well (possibly for things such as finding selection or incoming reference points, scroll positions, canonical storage URL).
This proposal would require an intermediate processor that understands the format to converts it into another serialization, such as JSON or RDF. The benefit would be ease of learning and use by the average Web developer, with a few simple rules (e.g. "use a note element as the container", "use a blockquote element to quote the source", "use @property to indicate who wrote the annotation and when", "add a tag @property for tags"). Any aspects of the annotation that are elided would be expected to be empty (i.e., irrelevant) or have default values, as appropriate.
<note id="annotation1">
<p>
<a property="annotatedBy" href="http://example.com/people/shepazu">Shepazu</a>
</p>
<time datetime="2014-01-14T01:28:22-0500">
<a href="http://example.com/annotations/shepazu-1389680902"
title="1:28 AM - 14 Jan 2014">A few minutes ago</a>
</time>
<blockquote cite="http://example.com/sourcedoc.html"
data-prefix="essential feature of the memex. "
data-suffix=" When the user is building a tra">
<p>The process of tying two items together is the important thing.</p>
<footer>
- <cite>
<a href="http://en.wikipedia.org/wiki/Vannevar_Bush">Vannevar Bush</a>
</cite>
</footer>
</blockquote>
<p>Annotations are at the Web's core.</p>
<ul>
<li property="tag">annotations</li>
<li property="tag">web</li>
<li property="tag">standards</li>
</ul>
</note>
Primary use cases revolve around variations on the selection anchoring schemes:
- Classic annotations (including comments) would include a robust anchor selector in the annotation itself, since a common use case is that the annotator doesn't control the document and can't insert a permanent link into it.
- Footnotes, where the document owner usually does have change control over the document source, the link could be in the document source rather than in the body of the annotation; this would also allow the author to add multiple links in the document body to the same footnote.
For footnotes (or other document-anchored notes), the standard HTML <a> element would be used, possibly with a special @property to indicate that it's linking to a <note> element. Such an anchor could contain text or not, depending on preference. For example:
<p>
Vannevar Bush described about the increased complexity, publication, and specialization
of scientific disciplines<a property="note" href="#annotation2" />. He proposed a new
machine for linking and sharing different sources of information, which he called a
<a property="note" href="#annotation2">memex</a>.
<p>
...
<note id="annotation1">
<cite>Bush, Vannevar (Jul 1945),
<a href="http://www.theatlantic.com/magazine/archive/1945/07/as-we-may-think/3881/">“As We May Think”</a>,
<i>The <a href="http://www.theatlantic.com/" title="Atlantic Monthly">Atlantic Monthly</a></i>
<b>176</b> (1): 101–8
</cite>
</note>
(Note: The footnote citation example above is deliberately simple, including no annotation body, annotation author or time, tags, or quotes; this is to emulate traditional citations. Other footnotes might be more complex.)
A note element could be styled using CSS in a variety of ways, from a sidebar positioned relative to the selection it references to a footer dynamically positioned at the bottom of the page where it is referenced in paginated content (e.g., an ebook).
JSON
JSON is frequently used as an interchange format, between applications or servers, or as a wire format for updates to web pages via XHR or sockets, where it is transformed using client-side JavaScript into HTML for the display format. It is also common as a storage format.
Here is a strawman for representing an annotation in JSON (actually, JSON-LD):
{
"@context": "http://www.w3.org/ns/oa.json",
"@type": "Annotation",
"annotatedAt": "2014-01-14T01:28:22-0500",
"annotatedBy": {
"@id": "http://example.com/people/shepazu",
"name": "Shepazu",
"@type" : "Person"
},
"hasBody": [
{
"chars" : "Annotations are at the Web's core."
},
{
"@type": "Tag",
"chars": [
"web",
"standards",
"annotations"
]
}
],
"hasTarget": "http://example.com/sourcedoc.html"
}
The simplicity of the code relies on http://www.w3.org/ns/oa.json context file including mapping not only for the OA terms but also for the frequently used terms from, say, CNT or FOAF. "@context" can also be omitted for those not using RDF, or if used on the Web, the context can also be transferred through an HTTP header.