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.

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

An annotation is a highlight if its motivation is set to "highlighting". In this case, its Selector should reference a range of characters, a region of an image or a time period.

An annotation is a bookmark if its motivation is set to "bookmarking". In this case, its [=Selector=] should reference a single point in the publication, not a range. If the [=Selector=] references a range, only the start of the range is used as a placeholder for the bookmark.

An annotation that does not include an explicit [=motivation=] is considered a bookmark.

Both highlights and bookmarks can have a Body, which is usually called a note or comment.

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

A Target with no Selector indicates that the annotation applies to the entire target resource.

A future version of the specification may add a way to reference another annotation by its unique identifier. This would allow annotations to target other annotations, enabling more complex annotation structures. In that case, we might introduce new [=Motivation] properties to indicate the relationship between annotations.

Source

The target resource MUST be identified by the relative URL of an existing EPUB top-level content document, as defined in [[epub-34]].

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

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:

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.

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

When a Text Position Selector is used on an HTML resource, it operates on a plain text serialization of the content using the Document Object Model `textContent` algorithm.

Character 0: Refers to the position immediately before the first character of the textContent of the scope. If the selector is a refinement, the scope is the element identified by the parent Selector; otherwise, the scope is the HTML <body> element.

Cross-Boundary Selection: When a selection spans multiple HTML elements, the parent Selector must identify a common ancestor of all involved nodes. The character stream is the concatenation of all text nodes within that ancestor, in tree order.

Robustness: To ensure persistence against DOM changes, the TextPositionSelector should be accompanied by a selector resistant to content modification and using the same serialization algorithm, e.g. the Text Fragment Selector. In cases of conflict (e.g., if the text has been modified), the latter should be used to re-calculate the correct offsets within the scope.

Refinement of a Selection

It may be more efficient or simpler to specify the segment of interest of a resource as a selection inside 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

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

The terms used for [=color=] and [=highlight=] (e.g., "pink", "orange", "solid", etc.) are only labels. They are not meant to denote precise values (e.g., `#ffc0cb` for "pink"). Instead, they represent the terms usually used by Reading Systems. The terms are mapped onto real values depending on factors like user preference (e.g. color themes) or device characteristics (e.g. display type).

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.

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",
            "highlight": "underline"
        }
    }

   {
        "@context": "https://www.w3.org/ns/epub-anno.jsonld",
        "type": "Annotation",
        "body": {
            "type": "Audio",
            "id": "./voice1.mp3",
            "tags": ["correction"],
            "color": "pink",
        }
    }

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
`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

About

The About object contains information relative to the publication. The following table lists recommended metadata fields, directly extracted from the metadata of the publication. They are intended to help associate an annotation set with a publication:

Name	Description	Format	Required?
`dc:title`	The title of the publication.	Localizable text	No
`dc:publisher`	The publisher of the publication.	Localizable text	No
`dc:creator`	The author(s) of the publication.	array of Localizable texts	No
`dc:date`	The publication date of the EPUB publication.	string (a W3C Date and Time Format is recommended but not required)	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.

The metadata of the publication may differ from the EPUB package document metadata. This happens when the publication metadata is manually updated by the user of the reading system, or when the reading system fetches metadata from an external source.

    {
        "@context": "https://www.w3.org/ns/epub-anno.jsonld",
        "id": "urn:uuid:123-123-123-123",
        "type": "AnnotationSet",
        "generated": "2023-09-01T10:00:00Z",
        "about": {
            "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": {
                }
            }
        ]
    }

Expectations of Reading Systems behavior

While this specification primarily defines an interchange format for EPUB annotations, this section outlines the expected behaviors, capabilities, or affordances of Reading Systems to ensure a consistent user experience and data interoperability across different environments.

Displaying and Filtering Annotations

To provide a useful user interface for managing annotations, Reading Systems are expected to:

Support metadata-based filtering: Allow users to filter the displayed annotations within a publication based on keys like [=motivation=] (e.g., distinguishing between a highlight and a bookmark), [=creator=], [=color=], [=highlight=], and user-defined [=tags=].
Handle multi-criteria filtering: Provide the capability to combine multiple filtering criteria simultaneously (e.g., filtering for annotations that are both tagged "review" and marked with a specific [=color=]) to help users manage large sets of annotations.

Generating and Processing Selectors

Because a publication may be modified or updated over time, the generation and robust processing of selectors are key to ensuring annotations remain attached to their correct positions.

When generating annotations, Reading Systems are expected to:

Create multiple selectors: Generate more than one type of selector for a single target whenever possible to ensure robustness against future modifications of the publication.

When processing annotations, Reading Systems are expected to:

Evaluate selectors by precision: Parse the array of Selectors in order of their precision (e.g., evaluating a FragmentSelector or CssSelector before falling back to broader text or range selectors).
Implement robust fallback logic: If the primary, or most precise selector fails to resolve because the underlying publication content has been modified, make an attempt to resolve the alternative selectors in the array.
Support core selector types: While Reading Systems have the freedom to implement only a subset of the selectors provided in this specification, they are expected to support the CssSelector, which is universally usable for both text and multimedia annotations.
Maintain degradation tolerance: Safely ignore unsupported selector types within an array without failing to process the annotation as a whole.

Importing Annotations and Conflict Resolution

The expectations for matching an annotation set to its target vary depending on how the data is delivered:

Embedded Annotation Sets: If the data is embedded directly within the publication, the target publication context is inherently known, and no external mapping is required.
Detached Annotation Sets: When a Reading System imports detached annotations, it is expected to check whether those annotations are indeed for the publication being rendered. Because there are no universally accepted identifiers for EPUB publications, this process involves heuristics that depend on the Reading System. These may include comparing the content of the package document with the metadata assigned to the imported annotations, or checking whether the target resources of the annotation selectors are valid.

To support this import workflow, Reading Systems are expected to:

Facilitate publication mapping: Use the user interface to make it easy for the user to map the data to the proper publication. This process may require direct user interaction via the interface.
Alert and inform the user: Provide clear information on the imported annotations to the user. If the metadata checks or validation heuristics detect a mismatch, the Reading System is expected to alert the user.
Prevent data duplication: Use the unique id of each Annotation to detect collisions once the publication context is verified. If an incoming annotation shares an id with an existing one, the system is expected to either update the existing entry or prompt the user for resolution, rather than creating a duplicate.

Exporting Annotations

The [=AnnotationSet=] structure does not exist natively inside a reading system; it is a serialization artifact used during the export process. When generating this structure for export, Reading Systems are expected to:

Adhere to standard serialization layouts: Create the [=AnnotationSet=] following the specification in section , ensuring that detached files or embedded container elements are placed in their specified locations.
Offer flexible export filtering: Provide users with options to filter annotations at export time, allowing them to export a specific subset (e.g., exporting only notes tagged "final" or highlights of a single [=color=]) rather than forcing the serialization of all internal annotation data.

Handling Unsupported Payload Types

The Web Annotation Data Model allows for rich media types that not all reading environments can parse. Reading Systems are expected to:

Degrade gracefully: If an annotation contains an audiovisual body (such as an image, audio, or video clip) that the current reading environment cannot render or play, ignore that specific annotation without disrupting the processing or rendering of other, textual annotations.
Inform the user: Provide a subtle visual indicator, placeholder, or notification to let the user know that an annotation exists at that location but its media content cannot be displayed due to format limitations.

Handling Fallbacks in top-level content documents

There may be cases where annotations are associated with foreign top-level content documents that the current reading environment cannot render. This is for instance the case if the annotation points to a section of image used as top-level content document, this image has a textual or svg fallback, and the reading system only supports textual or svg content as top-level content documents.

If a reading system encounters such a case, it is recommended to associate the annotation with the selected fallback representation, by mapping the annotation [=Selector=] to a representation supported by this content document. It is not recommended to store this mapped selector permanently.

Color Mapping

To ensure visual consistency across different reading environments, Reading Systems are expected to:

Map to a neutral default: If an annotation contains a [=color=] value outside of the standard enumerated profile (or one unsupported by the application's current theme), map it to a neutral fallback color (such as grey).
Standardize colors on export: If the application uses proprietary or system-specific color names internally, map those colors, when exporting the data, to the closest matching value from the enumerated profile colors defined for the [=color=] key.

Security Considerations

The EPUB Annotations specification provides a standardized data model for importing, exporting, and displaying annotations. Because annotations can originate from untrusted external sources—such as downloaded detached files (AnnotationSet) or crowd-sourced annotation servers—implementations must treat all incoming annotation data as potentially malicious.

Implementers should design reading systems and processing tools defensively to mitigate the risks of injection attacks, malicious resource loading, and denial-of-service, aligning with the guidelines in the W3C Self-Review Questionnaire: Security and Privacy.

Plain Text Handling and Cross-Site Scripting (XSS)

This specification restricts textual annotation bodies to plain text. Consequently, reading systems MUST NOT parse, interpret, or render HTML, XML, or script markup contained within an annotation's body.

Plain Text Enforcement: Reading systems must process any markup elements or entity references (such as <script> or <iframe>) strictly as raw text strings. When displaying annotation content within a web-based context or DOM element, reading systems must safely escape text or use plain-text insertion methods (e.g., textContent in JavaScript) to ensure that embedded code cannot execute.
Auto-linking Risks: If a reading system automatically parses plain text to render hyperlinked URLs within an annotation body, it must validate the URI scheme (limiting active links to secure protocols like https:) to prevent execution of malicious schemes such as javascript: or file:.

External Resources and Network Security

Annotations can reference external Web resources (e.g., in the target property or when referencing external media for audiovisual notes).

Automatic Fetching: Reading systems should not automatically fetch or render external resources linked in an annotation without explicit user consent. Automatic fetching can be exploited to conduct Server-Side Request Forgery (SSRF) attacks or to expose the user's IP address to third-party tracking servers.
Malicious URIs: Implementations must validate the URI schemes of all external resources, restricting active requests to secure protocols (e.g., https:) and blocking dangerous schemes (e.g., javascript:, file:, or OS-specific application handlers).
User Warnings: When an annotation prompts a user to open an external link, the reading system should clearly indicate that the destination is external to the EPUB package and inherently untrusted.

Path Traversal and Local Access

The [=Target] object utilizes a source property, which must be the URL of an existing resource within the EPUB package (e.g., an HTML document).

Container Bounding: When resolving the source URL against the EPUB package, reading systems must prevent path traversal attacks. Implementations must ensure that malicious paths (e.g., ../../../../etc/passwd or ../outside-container.html) cannot be used to escape the bounds of the EPUB container or access local system files.

Algorithmic Complexity and Denial of Service (DoS)

Processing deeply nested annotation data or calculating complex selectors can be weaponized to consume excessive CPU or memory, leading to a Denial of Service.

Selector Complexity: The [=Selector=] object (particularly CSS Selectors and Text Position Selectors) requires the reading system to traverse the Document Object Model (DOM) to locate specific segments. Attackers may craft overly complex CSS selectors or extreme text coordinate ranges designed to hang the rendering engine. Implementations should enforce execution time limits and depth limits when applying selectors.
JSON Parsing: As EPUB Annotations are serialized in JSON/JSON-LD, implementations must use secure parsing libraries configured to limit maximum file size, string length, and nesting depth to prevent memory exhaustion or "Billion Laughs"-style parser attacks.

Spoofing and Data Integrity

When annotations are imported from a detached [=AnnotationSet=], reading systems have no inherent guarantee of the data's authenticity.

Creator Forgery: The [=Creator=] object can be easily forged. An attacker could craft an annotation file that appears to come from a trusted source (such as a teacher, publisher, or known peer) but contains misleading or offensive notes.
Integrity Validation: Implementers should treat the [=Creator=] metadata in detached files as unverified unless the annotation set is transmitted over a secure, authenticated channel (like an authenticated API) or is cryptographically signed. Reading systems should visually distinguish between locally authored annotations and untrusted imported annotations.

Introduction

Relationship to URL