This section describes the status of this
document at the time of its publication. A list of current W3C
publications and the latest revision of this technical report can be found
in the
W3C standards and drafts index.
Publication as a First Public Working Draft does not
imply endorsement by W3C and its Members.
This is a draft document and may be updated, replaced, or obsoleted by other
documents at any time. It is inappropriate to cite this document as other
than a work in progress.
This document was produced by a group
operating under the
W3C Patent
Policy.
W3C maintains a
public list of any patent disclosures
made in connection with the deliverables of
the group; that page also includes
instructions for disclosing a patent. An individual who has actual
knowledge of a patent that the individual believes contains
Essential Claim(s)
must disclose the information in accordance with
section 6 of the W3C Patent Policy.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, and SHOULD in this document
are to be interpreted as described in
BCP 14
[RFC2119] [RFC8174]
when, and only when, they appear in all
capitals, as shown here.
In the Web Annotation model, the core structure is the
Annotation object,
which contains properties defining the annotation's
Body and Target.
EPUB Annotations reuse the same model with some restrictions specified in this document.
Subsequent sections provide more formal definitions for the terms used by this
specification.
Web Annotations may have 0 or more Bodies, whereas this document requires to have a single Body
per annotation. Furthermore, in the [annotation-model], such Body can be remote or embedded,
whereas only embedded Bodies are used in EPUB Annotation and only for textual comments .
Issue 2925: Annotations: the model may need a mechanism to include audiovisual comments. Spec-Annotations
At the moment, only textual annotations are described. Audovisual comments may come to the fore in the future.
Web Annotations have 1 or more Targets, while only a single Target is
allowed for an EPUB Annotation.
The Target of an EPUB Annotation is the content being annotated, which is
a specific segment in a document within the EPUB package defined by its relative
Source URL and a Selector.
Web Annotations may have multiple motivations, while only a single motivation is allowed for EPUB
annotations.
Web Annotations may have multiple creators, while only a single creator is allowed for EPUB
annotations.
Web Annotations may have additional properties that are not accepted for EPUB Annotations (see the
definitions of the properties in later sections). For example,
a specific generator application and generated date may exist for a Web Annotation,
whereas this document only defines these properties for Annotation Sets.
Web Annotations also define additional property values and types than are not accepted for EPUB Annotations.
Web Annotations define an Annotation Collection structure to handle paginated requests,
whereas this document defines an AnnotationSet structure to group multiple annotations for sharing purposes.
Implementers MUST support AnnotationSet and MAY support both structures for maximum compatibility.
Note
This document does not define how annotations are created, stored, or synchronized in a reading system.
2.1 Relationship to URL
To be consistent with EPUB 3.4, this specification refers to the [url] standard for terminology
and processing related to URLs expressed in EPUB publications and in Annotations Objects.
The additional constraints expressed in EPUB 3.4 also apply.
Note that this is a difference with the Web Annotation Data Model which uses the term IRI [rfc3987]. This difference does
not alter the structure of the Data Model used by this specification.
The [annotation-model] specification is fairly open ended as for the value of, for
example, the body property. This specification restricts the value by defining specific classes that
must be used, see the definitions for
Creator, Target, and Body below.
Note
The type of annotation should be considered when determining the value of the
motivation property.
An annotation with a Body structure corresponds to a "comment".
An annotation without Body structure corresponds to a "highlight" if its Selector defines a range of
characters, a space in an image
or a time period, and a "bookmark" if it does not.
Editor's note
We should specify whether a property may appear at most once (body, target) because
that is also part of
the profile definition. This can be a separate column ("cardinality") or be added to the
description. This remark may be valid
for all the tables in the document.
In the section titled "Subset of the Web Annotation Data Model" we say:
The Target of an EPUB Annotation is the content being annotated, which is a specific segment in a document within the EPUB package defined by its relative Source URL and a Selector.
However, we do not require the target to be a specific segment in a document, unless we are including the entire document with no range specified as a "segment in" that document. I am actually not sure why we need to define target here at all? There are a lot of nuances (for instance, I am not sure from this definition if selector is required), and this is just a list of changes from web annotations, which is really only interesting to people that know what is in web annotations, and hence are likely aware of how target is used.
Describe the fix or new feature you propose
I propose deleting the second sentence of this bullet point.
3.2 Creator
The Creator object of an annotation is a person, an organization or a software agent.
This document defines the following creator properties:
Name
Description
Format
Required?
id
The identity of the creator.
URL
Yes
type
Type of the creator. It MUST be "Person", "Organization" or "Software".
string
Yes
name
The name of the creator.
string
No
3.3 Target
The Target object of an annotation associates the annotation with a specific segment of a
resource in the current publication.
This document defines three target sub-properties:
Name
Description
Format
Required?
source
The identity of the target EPUB resource.
URL
Yes
selector
The segment of the target EPUB resource that is annotated.
Array of Selector objects
No
meta
Indications that help locate the segment in the resource.
Meta
No
A Target with no Selector indicates that the annotation applies to the entire
target resource.
3.3.1 Source
The target resource MUST be identified by the URL of an existing resource in the
EPUB package. It MUST be one of the item/@href values of the manifest element as
defined in [epub-34].
3.3.2 Selector
An annotation refers to a segment of a resource, which is identified by one or more
Selectors.
The nature of the Selectors and methods to describe segments depend on
the resource type. Providing more than one Selector allows an annotation software to
choose the most accurate selector from those it can handle and helps to accommodate
evolutions on the annotated resource.
Several annotation selectors are specified in the
Web Annotation Data Model.
This specification retains selectors (with possible restrictions) deemed useful for
annotating EPUB publications, and details on how to use these selectors.
3.3.2.1 Fragment Selector
The Fragment Selector object uses the fragment part of an URL defined by the
representation's media type. This object is identical in structure to the
Fragment Selector defined by
Web Annotation Data Model, except that it restricts the media types it may use.
Name
Description
Format
Required?
type
The RDF structure type. It MUST be "FragmentSelector".
string
Yes
value
The contents of the fragment component of an URL that describes the selection.
The selector MUST have exactly 1 value property.
string
Yes
conformsTo
Provides the reference to the specification that defines the syntax of the URL
fragment in the
value property. The selector SHOULD have exactly 1 conformsTo link
to
the specification that defines the syntax of the fragment and MUST NOT have more
than 1.
One of the URL strings listed in the table below.
No
The following URLs are the specifications that define the semantics of fragments, and hence
may be used with the
conformsTo property. Other URLs MUST NOT be used.
This selector, used with text fragments, must be used with great care when the number
of characters that can be copied from the publication is constrained by the publisher.
Note
The integration of text fragments into the specification is AT RISK.
The reason is two-fold:
The specification is currently a Draft Community Group Report. While there is an
activity to include it into the HTML Standard [html], this is still ongoing.
It may not be finalized by the time this specification goes to Recommendation.
See also whatwg#11895.
The integration of text fragments selector in reading systems is very challenging:
the absence of a standard API in web browsers makes mapping a text fragment to
a DOM Range difficult.
Rebuilding a DOM range from a textual range using tree walking is suboptimal,
and the existing polyfills are not well-maintained. This fragment specification
cannot be retained unless a public API is defined and implemented in major web
browsers.
See also whatwg#8282
3.3.2.2 CSS Selector
This section is non-normative.
One of the most common ways to select elements in the HTML Document Object Model is to use
CSS Selectors [CSS3-selectors]. This specification reuses the CssSelector, as defined in
the Web Annotation Data Model specification, but lists it here for an easier readability.
Name
Description
Format
Required?
type
The RDF structure type. It must be "CssSelector".
string
Yes
value
The CSS selection path to the target.
The selector must have exactly 1 value property.
string
Yes
3.3.2.3 Text Position Selector
This section is non-normative.
This Selector describes a range of text by recording the start and end positions of the
selection in the stream.
Position 0 would be immediately before the first character, position 1 would be immediately
before the second character, and so on.
This specification reuses the TextPositionSelector,
as defined in the Web Annotation Data Model specification, but lists it here for an easier
readability.
Name
Description
Format
Required?
type
The RDF structure type. It must be TextPositionSelector.
string
Yes
start
The starting position of the segment of text. The first character in the full
text is character position 0, and the character is included within the segment.
Each TextPositionSelector must have exactly 1 start
property, and the value must be a non-negative integer.
non-negative integer
Yes
end
The end position of the segment of text. The character is not included within
the segment.
Each TextPositionSelector must have exactly 1 end
property, and the value must be a non-negative integer.
non-negative integer
Yes
The text must be selected and normalized in the same way as for the Text Quote Selector before counting the
number of characters to determine the start and end positions.
Issue 2927: Annotations: the details of the text position selectors may be underspecified Spec-Annotations
This is an "inherited" class, but seems to be underspecified on how to get to the right position. Some text may have to be added specifying that:
if the selector is part of a refinement, it should use the innerText of the previously selected HTML fragment; otherwise
it should use the innerText of the <body>
3.3.2.4 Refinement of Selection
It may be easier, more reliable, or more accurate to specify the segment of interest of a
resource as a selection of a selection, rather than as a selection of the complete resource.
This is accomplished by having selectors chained together, where each refines the results
of the previous one.
The Web Annotation Data Model specification defines the refinedBy
property. This specification restricts the possible values of the property to include only
those selectors that are specified by, or listed in this specification.
Name
Description
Format
Required?
refinedBy
The relationship between a broader selector and the more specific selector that
SHOULD be applied to the results of the first.
A Selector MAY be refined by 1 or more other Selectors. If more than 1 is
given, then they are considered to be alternatives that will result in
the same selection.
This selects "q" from "quick" as start position and
"x" from "fox" as end position in the following HTML snippet:
<divid="intro"><p>Some text.</p><p>The quick <em>brown</em> fox jumps over the lazy dog.</p><p>The lazy <em>white</em> dog sleeps with the crazy fox.</p></div>
The Body object uses the language and textDirection terms for international texts. This is inherited from the Web Annotation spec, which was created when text directionality was not properly handled in JSON-LD. However, JSON-LD now has the @language and @direction keywords that properly covers this, see String Internationalization.
Describe the fix or new feature you propose
I would propose to rely on the JSON-LD spec, possibly aliasing the language and direction terms to the keywords.
4. Annotation Set
An Annotation Set is an unordered collection of annotations.
An Annotation does not contain information about its associated publication. If a
set of annotations is shared as a detached file, it is mandatory to also export
information that will help find the associated publication even if the publication
is not adequately identified.
Note
The AnnotationCollection defined
in the Web Annotation Data Model does not provide an adequate
structure for sharing annotations either as a detached file or as a file embedded in
a Zip package. The AnnotationCollection provides a
way to retrieve annotations via a REST API and is, therefore, intrinsically paginated.
The AnnotationSet contains:
Name
Description
Format
Required?
id
The identity of the annotation set. A uuid formatted as a URN is
RECOMMENDED.
URL
Yes
type
It MUST be AnnotationSet.
string
Yes
generator
The agent responsible for the generation of the object serialization.
There two terms, namely name and title that appear in our annotation spec meaning, more or less, the same thing: giving a human readable identification of some sort to a resource. We have
title for an Annotation set
name for a Generator and for Creator.
4.1 Generator
The Generator object contains information relative to the software from which the
serialized annotation has been produced.
Name
Description
Format
Required?
id
The identity of the generator software. The recommended value is the
GitHub URL of the application source code.
URL
Yes
type
The RDF type. It MUST be "Software".
string
Yes
name
The name of the generator software.
string
Yes
homepage
The home page presenting the generator software.
URL
No
4.2 About
The About object contains information relative to the publication. Such metadata is
intended to help associate an annotation set with a publication:
Following the Web Annotation Data Model [annotation-model] specification, EPUB Annotations are
expressed as a "shape" of JSON-LD [json-ld11] (a variant of JSON [ecma-404] for linked data).
The shape is informally defined through a JSON Schema [json-schema]; see 7. JSON Schema
for further details.
The media type of this format is
application/ld+json;profile="http://www.w3.org/ns/anno.jsonld"
This specification introduces a dedicated file extension for serialized
AnnotationSets: .annotation.
Following the requirements of JSON-LD, each annotation file (whether a single annotation or an
annotation set) MUST start with a context declaration referring to the following, EPUB Annotation
specific context: https://www.w3.org/ns/epub-anno.jsonld.
This context file imports (using the imported contexts
feature of JSON-LD) the "core" context file of the Web Annotation Data Model [annotation-model], i.e.,
https://www.w3.org/ns/anno.jsonld.
The EPUB Annotation specific context file contains terms extending, an sometimes overriding the terms
in the core annotation context file, as defined in this specification.
Note
Implementations that do not rely on the linked data aspects of annotations may rely on bespoke
processing based on the shape of the annotation or the annotation set.
Such implementations may safely ignore the context
declarations and are not required to dereference the respective URLs.
6. Embedding annotations in EPUB
The OPTIONAL my.annotation file in the META-INF directory holds an
AnnotationSet.
6.1 Best Practices for Reading Systems
This section is non-normative.
Editor's note
This section being informative, the MUST, SHOULD, etc, keyword are not appropriate
here. At the minimum, they should be turned into lower case.
6.1.1 Displaying filtered annotations
Reading systems should enable filtering by motivation, color, highlight mode, tag and
creator. For instance, a user can display "blue" annotations only or
“teacher” annotations only. Filtering on multiple criteria is a plus.
6.1.2 Using multiple selectors
It is recommended that Reading Systems export multiple selectors, including at least
one precise selector (e.g. CssSelector + TextPositionSelector),
and one selector resistant to content modifications (e.g., based on text fragments).
When displaying an annotation, a Reading System is free to use the most precise
Selector available. It will select an alternative Selector as a fallback in case the
preferred one does not return a correct position in the publication: this can happen
if the publication has been modified after the annotation has been created.
Not all selectors are equally easy to implement. Reading Systems MAY choose to
support only a subset of the selectors defined in this specification.
The W3C Publishing Maintenance Working Group is expected to define one or more selectors
reading systems are required to implement, as a lingua franca.
6.1.3 Exporting annotations as a detached file
When a user decides to export an annotation set from a reading system, they SHOULD be
proposed to filter the annotations by tags (multiple choice). “Annotations with
no tag” and “All annotations” SHOULD be proposed as options. The advantage of
this practice is that, for instance, a user can export personal annotations (usually
with no tag) and leave “teacher” annotations unexported.
They MAY enter a title for the annotation set (empty by default). Such a title SHOULD
become the exported filename.
They MUST be able to choose the directory in which the annotation set will be stored.
The file extension MUST be .annotation .
The application may propose alternative formats at export time: an HTML or markdown format
with human-friendly references to the location of each annotation may be handy.
6.1.4 Exporting annotations in a publication
When a user decides to export a publication from the Reading System, they SHOULD be
prompted to embed the annotations associated with the publication.
If the user decides to embed annotations in a publication, they SHOULD be prompted to
filter the annotations by tags (multiple choice).
6.1.5 Importing annotations
To simplify associating annotations with a publication, a Reading System MUST
offer a way to select a publication before selecting an annotation set. The drag and
drop of an annotation set into a Reading System MAY also be proposed, but
identifying the proper publication from the metadata in the annotation set is more
complicated.
When importing an annotation set, a Reading System SHOULD display a message with the
title of the annotation set and the number of annotations in the set. The Reading
System MUST offer the user the choice to abort the import.
Each annotation is uniquely identified. If during the import of an annotation set,
one or more annotations are re-imported, the Reading System MUST offer to the user
the choice to override existing annotations or abort the import of the annotation
set.
6.1.6 Dealing with colors
This document specifies a closed set of six colors chosen because of their
extensive support in well-known reading systems. However, most existing reading apps
offer a smaller set to their users.
If an application imports annotations with a color it does not support, it should
display them with a neutral color. The recommended neutral color is grey.
Some applications may support colors not in the set defined by this specification
(e.g. brown). In this case, a 1-to-1 substitution at export time is required (e.g.
brown to orange).
Note
We didn't spot applications with more than six annotation colors.