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-anno-ucr]]] [[epub-anno-ucr]].

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" \| "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 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. 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": "https://www.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 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

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

                {
                    "@context": "https://www.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 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 uses.

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:

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

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.

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.

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

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" \| "TextQuoteSelector" \| "TextPositionSelector"	No

                        
                            {
                                "selector": [
                                    {
                                        "type": "CssSelector",
                                        "value": "#intro > p:nth-child(2)",
                                        "refinedBy": {
                                            "type": "TextPositionSelector",
                                            "start": 4,
                                            "end": 19
                                        }
                                    }
                                ]
                            }

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>

Body

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

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
`tags`	Free text categorizing the annotation.	Array of string	No

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

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

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 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.	[=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.	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: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": "https://www.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": {
                }
            }
        ]
    }

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, tag 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., 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.

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.

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

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

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

Subset of the Web Annotation Data Model