This document defines a profile of the [[[annotation-model]]] [[annotation-model]] by specifying a subset of the terms, and adding terms deemed useful to satisfy the entries in the [[[epub-anno-ucr]]] [[epub-anno-ucr]] document.

Introduction

This section defines a profile of the [[[annotation-model]]] [[annotation-model]], as used for EPUB Annotations.

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.

This document does not define how annotations are created, stored, or synchronized in a reading system.

Relationship to URL

To be consistent with [[[epub-34]]], 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 also apply. Note that this is a difference with the [[[annotation-model]]] which uses the term IRI [[rfc3987]]. This difference does not alter the structure of the Data Model used by this specification.

Annotation

Annotation Object

The Annotation object retains the following annotation properties from the Web Annotation object [[annotation-model]]:

Name Description Format Required?
id The identity of the annotation. A uuid formatted as a URN is RECOMMENDED. URL Yes
type The RDF structure type. It MUST be "Annotation". string Yes
motivation The motivation for the annotation's creation. "bookmarking" | "highlighting" No
created The time when the annotation was created. ISO 8601 datetime Yes
modified The time the annotation was modified after creation. ISO 8601 datetime No
creator The creator of the annotation. This may be a human, an organization or a software agent.
 [=Creator object=] No
target The target content of the annotation. [=Target object=] Yes
body The annotation body. [=Body object=] No

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.

The type of annotation should be considered when determining the value of the [=motivation=] property. The motivation is "highlighting" if the Selector defines a range of characters, a space in an image or a time period. It is "bookmarking" if the Selector references a single character in the resource. A textual or audiovisual body may be present in both cases.

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.

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. Localizable text No

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.

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]].

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.

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 [[[annotation-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.

Name Fragment Specification Description
HTML http://tools.ietf.org/rfc/rfc3236 [[rfc3236]]. Example: namedSection
Media http://www.w3.org/TR/media-frags/ [[media-frags]]. Example: xywh=50,50,640,480 or t=10,20
SVG http://www.w3.org/TR/SVG/ [[svg11]]. Example: svgView(viewBox(50,50,640,480))
Text fragment https://wicg.github.io/scroll-to-text-fragment/ [[scroll-to-text-fragment]]. Example: :~:text=an%20example,text%20fragment

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.

The integration of text fragments into the specification is AT RISK. The reason is two-fold:

  1. 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.
  2. 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

CSS Selector

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 [[[annotation-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

Text Position Selector

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 [[[annotation-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.

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 [[[annotation-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. "FragmentSelector" |
"CssSelector" |
"TextPositionSelector"
 No

This selects "q" from "quick" as start position and "x" from "fox" as end position in the following HTML snippet: 

<div id="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>

Meta

The Meta object… T.B.D.

Body

The Body object of an annotation contains either plain text and style information, or a reference to an external audiovisual resource. It can also include optional tags.

This document specifies the following sub-properties of annotations:

Name Description Format Required?
type The body type. "TextualBody" | "Image" | "Audio" | "Video" The body type. It MUST be “TextualBody”. string Yes
format The media-type of the note. Only plain text is allowed for textual notes. Audiovisual notes can be of any media type supported by EPUB, see EPUB Media Types. string No
value The content of a textual note. Localizable text Yes, if type is "TextualBody". Not applicable for audiovisual notes.
id The relative URL of the audiovisual note. URL Yes, if type is "Image", "Audio", or "Video". Not applicable for textual notes.
tags Free text categorizing the annotation. Array of string No

The format for a "TextualBody" is restricted to plain text. Markdown was also considered, but current practice among Reading Systems is to use text without any formatting in annotations. Consequently, defining Markdown as an alternative in the exchange format would have very little chance of being implemented. A further issue is the great variety of Markdown-based formats, without any one being stable enough to be referenced normatively. Future versions of this specification may reconsider this.

The URL referencing an audiovisual note must be the relative URL of the resource in a serialized AnnotationSet.

Implementers are free to add other properties, as long as they are properly declared in the context file.

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.

The AnnotationCollection defined in the [[[annotation-model]]] does not provide an adequate structure for sharing annotations either as a detached file or in an EPUB 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. [=Generator=] No
generated The time when the set was generated. ISO 8601 datetime No
about Information relative to the publication. [=About=] Yes
items The set of annotations. Array of Annotation objects Yes

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

About

The About object contains information relative to the publication. Such metadata is intended to help associate an annotation set with a publication:

Name Description Format Required?
dc:identifier Publication identifiers. An ISBN is preferred. Array of strings No
dc:format The media type of the publication. string No
dc:title The title of the publication. Localizable text No
dc:publisher The name of the publisher. Localizable text No
dc:creator The author(s) of the publication. array of Localizable texts No
dc:date The release year. calendar year using four digits No

All properties are from the Dublin Core Vocabulary [[dcterms]], also referenced in the [[[annotation-model]]] as well as in the EPUB package document metadata. Implementers are free to add other properties from the Dublin Core Vocabulary, or to use properties from other vocabularies, as long as they are properly declared in the context file.

Serialization of an AnnotationSet

Following the [[[annotation-model]]] [[annotation-model]] specification, EPUB Annotations are expressed as JSON-LD [[json-ld11]] (a variant of JSON [[ecma-404]] for linked data). The model is informally defined through a JSON Schema [[json-schema]]; see for further details. The media type of this model is application/ld+json;profile="http://www.w3.org/ns/anno.jsonld"

Following the requirements of JSON-LD, each annotation file 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 [[[annotation-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.

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.

Detached annotations

For packaging the set of constituent resources that comprise an AnnotationSet, this specification uses the ZIP format as specified in ISO/IEC 21320-1:2015 ([[ISO21320]] and [[zip]]).

This specification introduces a dedicated file extension for detached annotations: .annotations.

The media type of this file is application/zip;profile="https://www.w3.org/TR/epub-anno-10/".

The serialized AnnotationSet is stored in the ZIP file as annotations.json, in the root of the ZIP file. Audiovisual notes, if present, MAY be in any location descendant from the root of the ZIP file. Annotation bodies within the AnnotationSet MUST reference these resources via relative-URL strings [[url]].

The [[zip]] specification has few constraints on the characters allowed for file and directory names. When crafting such names, authors must be careful to use characters which allow a broad interoperability among operating systems.

Annotations embedded in EPUB

The AnnotationSet is stored in the META-INF directory as annotations.json. Audiovisual notes, if present, MAY be in any location descendant from the META-INF directory, or in the META-INF directory itself. Annotation bodies within the AnnotationSet MUST reference these resources via relative-URL strings [[url]].

Storing audiovisual notes in the META-INF directory has implications for the size of the EPUB package, and is therefore not recommended.

Best Practices for Reading Systems

Displaying filtered annotations

It is recommended that Reading systems enable filtering by motivation, creator, style and tags. For instance, a user can display "blue" colored annotations only, or "typo" tagged annotations only. Filtering on multiple criteria is a plus.

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 are free to choose to support only a subset of the selectors defined in this specification.

Exporting annotations as a detached file

When a user decides to export an annotation set from a reading system, it is good to propose them to filter annotations by motivation, creator, style and tags. The advantage of this practice is that, for instance, a user can export personal annotations only.

The application can propose alternative formats at export time: an HTML or markdown format with human-friendly references to the location of each annotation is handy.

Exporting annotations embedded in an EPUB

When a user decides to export a publication from the Reading System, it is good to propose them to embed the annotations associated with the publication.

If the user decides to embed annotations in the publication, they should be prompted to filter the annotations.

Importing annotations

To simplify associating annotations with a publication, a Reading System has to offer a way to select a publication before selecting an annotation set. An automatic association of an annotation set with a publication (e.g. via drag and drop) can also be proposed, but identifying the proper publication from the metadata in the annotation set is error prone.

When importing an annotation set, the good practice for Reading Systems is to display publication metadata (e.g. title, author), the number of annotations found in the set, and offer the user the choice to abort the import if the information does not match their expectations.

Each annotation is uniquely identified, independently of the annotation set it is part of. During the import of an annotation set, if one or more annotations are found to be already stored in the application, the Reading System will offer the user a choice: either overriding the existing annotations, or abort the import of the annotation set.

Dealing with audiovisual notes

This specification provides mechanisms for handling audiovisual notes.

If an application does not support audiovisual notes, it has to ignore them when importing an annotation set. It is good practice to notify the user that some annotations were not imported due to lack of support.

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 is good practice to ignore the color information and to 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 import or export time is required (e.g. mapping brown to orange).

We didn't spot applications with more than six annotation colors.

JSON Schema

T.B.D.

Internationalization Considerations

Localizable texts

The EPUB Annotation model inherits the string internationalization features defined by [[[json-ld11]]]. These may be used for values that are defined as localizable texts. To set the right language metadata, the value is a separate object with the string value set explicitly through the `stringValue` property. The `language` and `direction` properties can be used to set the language tag and the string direction, respectively. The value for `language` is a string representing a [[BCP47]] language tag. The value for `direction` is a string whose value must be either `"ltr"` or `"rtl"`.

In the example below, two annotations within the same [=AnnotationSet=] use different languages. In the second annotation the string direction is also set to ensure the correct rendering of the text with mixed Latin and Hebrew characters.

Setting the default values

The default values for `language` and `direction` may be set as part of the context declaration of the Annotation Set. The value of the top-level `@context` must be extended with an extra context object (using the JSON array notation) containing the default setting using the the `@language` and `@direction` keywords. See the example below as an alternative for the previous example.

The extra object in the context can be used whenever a context is set. For example, it is possible to set the default value for a single annotation.

Privacy Considerations

T.B.D.

Security Considerations

T.B.D.