This document defines a profile of the [[[annotation-model]]] [[annotation-model]] by specifying a subset of the properties allowed in this model, and adding properties deemed useful to satisfy the [[[epub-ann-ucr]]] [[epub-ann-ucr]].

Subset of the Web Annotation Data Model

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 listed below. 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 for textual comments .
The inclusion mechanism is to be defined for audiovisual comments
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 usable for EPUB Annotations.
Web Annotations define an AnnotationCollection 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.

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

Annotation

Annotation Object

This document retains the following annotation properties from the Annotation object [[annotation-model]]:

Name	Description	Format	Required?
`id`	The identity of the annotation. A uuid formatted as a URN is RECOMMENDED.	URI	Yes
`type`	The RDF structure type. It MUST be "Annotation".	string	Yes
`motivation`	The motivation for the annotation's creation.	"bookmarking" \| "commenting" \| "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 either a human or an organization.	[=Creator=]	No
`target`	The target content of the annotation.	[=Target=]	Yes
`body`	The annotation body.	[=Body=]	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. 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.

Question: should we add a "replying" motivation for annotations that are replies to other annotations?

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.

                {
                    "@context": [
                        "http://www.w3.org/ns/anno.jsonld",
                        "https://wwww.w3.org/ns/epub/anno.jsonld"
                    ],
                    "id": "urn:uuid:123-123-123-123",
                    "type": "Annotation",
                    "created": "2023-10-14T15:13:28Z",
                    "modified": "2024-01-29T09:00:00Z",
                    "target": {
                        …
                    },
                    "body": {
                        …
                    }
                }

Creator

The Creator of an annotation is a person or an organization.

This document defines the following creator properties:

Name	Description	Format	Required?
`id`	The identity of the creator.	URI	Yes
`type`	Type of the creator. It MUST be "Person" or "Organization".	string	Yes
`name`	The name of the creator.	string	No

Target

The Target 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.	URI	Yes
`selector`	The segment of the target EPUB resource that is annotated.	An 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]].

                {
                    "@context": [
                        "http://www.w3.org/ns/anno.jsonld",
                        "https://wwww.w3.org/ns/epub/anno.jsonld"
                    ],
                    "type": "Annotation",
                    "target": {
                        "source": "OEBPS/text/chapter1.html",
                        "selector": [
                        …
                        ],
                        "meta": {
                        …
                        }
                    }
                }

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 accommodate evolutions on the annotated resource.

Annotation selectors are specified in Web Annotation Data Model. This specification retains selectors deemed useful for annotating publications and details on how to use these selectors.

New selectors will undoubtedly be defined in the coming months after discussion with members of the W3C Publishing Maintenance Working Group.

Body

The Body of an annotation contains plain text, style, and an optional keyword.

This document specifies the following sub-properties:

Name	Description	Format	Required?
`type`	The body type. It MUST be “TextualBody”.	string	Yes
`value`	The textual content of the annotation.	string	Yes
`format`	The media-type of the annotation value; "text/plain" by default; "text/markdown" is recommended.	[[RFC6838]], [[RFC7763]]	No
`color`	The color of the annotation; yellow by default.	"pink" \| "orange" \| "yellow" \| "green" \| "blue" \| "purple"	No
`highlight`	The style of the annotation; solid background by default.	"solid" \| "underline" \| "strikethrough" \| "outline"	No
`language`	The language of the annotation.	[[BCP47]]	No
`textDirection`	The direction of the text; left-to-right by default.	"ltr" \| "rtl"	No
`keyword`	Free text categorizing the annotation.	string	No

Read “Best practices for Reading Systems” about using a keyword in an annotation.

    {
        "@context": [
            "http://www.w3.org/ns/anno.jsonld",
            "https://wwww.w3.org/ns/epub/anno.jsonld"
        ],
        "type": "Annotation",
        "body": {
            "type": "TextualBody",
            "value": "j'adore !",
            "keyword": "teacher",
            "color": "blue",
            "language": "fr",
            "textDirection": "ltr"
        }
    }

Annotation Set

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 as a file embedded in a Zip package. The AnnotationCollection meant to provide a way to retrieve annotations via a REST API and is, therefore, intrinsically paginated.

The AnnotationSet object contains:

Name	Description	Format	Required?
`id`	The identity of the annotation set. A uuid formatted as a URN is RECOMMENDED.	URI	Yes
`type`	It MUST be `AnnotationSet`.	string	Yes
`generator`	The agent responsible for the generation of the object serialization.	[=Generator=]	No
`about`	Information relative to the publication.	[=About=]	Yes
`generated`	The time when the set was generated.	ISO 8601 datetime	No
`title`	A title to help identifying the set.	string	No
`items`	The annotations of the set.	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.	URI	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:title`	The title of the publication.	string	No
`dc:format`	The media type of the publication.	string	No
`dc:publisher`	The name of the publisher.	string	No
`dc:creator`	The author(s) of the publication.	array of strings	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.

    {
        "@context": [
            "http://www.w3.org/ns/anno.jsonld",
            "https://wwww.w3.org/ns/epub/anno.jsonld"
        ],
        "id": "urn:uuid:123-123-123-123",
        "type": "AnnotationSet",
        "generator": "https://github.com/edrlab/thorium-reader/releases/tag/v3.1.0",
        "generated": "2023-09-01T10:00:00Z",
        "title": "Annotations Mme Prof, La Peste, cours 1ere B",
        "about": {
            "dc:identifier": [
                "urn:isbn:1234567890"
            ],
            "dc:format": "application/epub+zip",
            "dc:title": "Alice in Wonderland",
            "dc:publisher": "Example Publisher",
            "dc:creator": ["Anne O'Tater"],
            "dc:date": "1865"
        },
        "items": [
            {
                "id": "urn:uuid:234-234-234-234",
                "type": "Annotation",
                "target": {
                },
                "body": {
                }
            }
        ]
    }

Serialization

Following the [[[annotation-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 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 contexts:

Context URL	Description
`http://www.w3.org/ns/anno.jsonld`	Core context file for the [[[annotation-model]]].
`https://wwww.w3.org/ns/epub/anno.jsonld`	Specific terms for EPUB Annotions extending, an sometimes overriding the terms in the core context file.

                    {
                        "@context": [
                            "http://www.w3.org/ns/anno.jsonld",
                            "https://wwww.w3.org/ns/epub/anno.jsonld"
                        ],
                        "id": "urn:uuid:123-123-123-123",
                        …
                    }

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.

The problem has been raised that implementers/users will forget to add two context declarations. A possibility is to use the imported contexts feature of JSON-LD, where the new context file would import the first one.
In theory, it is also possible to copy the relevant declarations of the core annotation context into the new one, but that approach may be too brittle (and would also require manual, and error prone, editorial work).
Both approaches would, however, simplify the structure of this section, too.

Embedding annotations in EPUB

The OPTIONAL my.annotation file in the META-INF directory holds an [=AnnotationSet=].

Best Practices for Reading Systems

This section being informative, the MUST, SHOULD, etc, keyword are not appropriate here. At the minimum, they should be turned into lower case.

Displaying filtered annotations

Reading systems should enable filtering by motivation, color, highlight mode, keyword and creator. For instance, a user can display "blue" annotations only or “teacher” 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. ProgressionSelector).

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.

Exporting annotations as a detached file

When a user decides to export an annotation set from a reading system, he SHOULD be proposed to filter the annotations by keywords (multiple choice). “Annotations with no keyword” 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 keyword) 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.

Exporting annotations in a publication

When a user decides to export a publication from the Reading System, he SHOULD be prompted to embed the annotations associated with the publication.

If the user decides to embed annotations in a publication, he SHOULD be prompted to filter the annotations by keywords (multiple choice).

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.

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.