EPUB Annotations 1.0

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

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

Note

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

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.

Issue 2884: Target is not necessarily a specific segment, but we say it is Spec-Annotations

No response

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.

I propose deleting the second sentence of this bullet point.

Example 1: Core structure of an EPUB annotation

{
    "@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": {
        …
    }
}

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

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.

Note

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.

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

Example 2: the source of the annotation is the relative URL identifying an HTML document in an EPUB

{
    "@context": "https://www.w3.org/ns/epub-anno.jsonld",
    "type": "Annotation",
    "target": {
        "source": "OEBPS/text/chapter1.html",
        "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.

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.

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`

Caution

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

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

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

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.

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

Example 3: a CSS Selector refined by a Text Position Selector


    {
        "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>

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

Note

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

Note

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.

Note

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

Example 4: An annotation Body

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

Example 5: An audio Body

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

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

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

Note

All properties are from the Dublin Core Vocabulary [dcterms], also referenced in the Web Annotation Data 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.

Note

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.

Example 6: An AnnotationSet containing one annotation

{
    "@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": {
            }
        }
    ]
}

Following the Web Annotation Data 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 8. JSON Schema for further details. The media type of this model is application/ld+json;profile="http://www.w3.org/ns/anno.jsonld"

Example 7: Required context declaration

{
    "@context": "https://www.w3.org/ns/epub-anno.jsonld",
    "type": "AnnotationSet",
    "id": "urn:uuid:123-123-123-123",
    …
}

The data model is inherently extensible: implementations may add reading system dependent terms, e.g., a reference to user color profiles.

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.

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.

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.

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.

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 5. Serialization of an AnnotationSet, 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.

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.

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.

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.

T.B.D.

This section is non-normative.

The EPUB Annotation model inherits the string internationalization features defined by JSON-LD 1.1. 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.

Example 8: Setting the language explicitly for localizable texts

{
    "@context": "https://www.w3.org/ns/epub-anno.jsonld",
    "type": "AnnotationSet",
    "id": "urn:uuid:123-456-789",
    "items" : [
        {
            "id": "urn:uuid:123-456-789-a1",
            "type": "Annotation",
            "body" : {
                "type": "TextualBody",
                "value": {
                    "language": "en",
                    "text": "HTML is a markup language.",
                }
            },
            "target" : {
                …
            }
        },
        {
            "id": "urn:uuid:123-456-789-a3",
            "type": "Annotation",
            "body": {
                "type": "TextualBody",
                "value": {
                    "language": "he",
                    "direction": "rtl",
                    "text": "HTML היא שפת סימון."
                }
            },
            "target": {
                …
            }
        },
        …
    ]
}

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.

Example 9: Setting the default language to English

{
    "@context": [
        "https://www.w3.org/ns/epub-anno.jsonld",
        {
            "@language": "en"
        }
    ],
    "type": "AnnotationSet",
    "id": "urn:uuid:123-456-789",
    "items" : [
        {
            "id": "urn:uuid:123-456-789-a1",
            "type": "Annotation",
            "body": {
                "type": "TextualBody",
                "value": "HTML is a markup language."
            },
            "target": {
                …
            }
        },
        {
            "id": "urn:uuid:123-456-789-a3",
            "type": "Annotation",
            "body": {
                "type": "TextualBody",
                "value": {
                    "language": "he",
                    "direction": "rtl",
                    "text": "HTML היא שפת סימון."
                }
            },
            "target": {
                …
            }
        },
        …
    ]
}

Note

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.

T.B.D.

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

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.

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.

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.

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.

about §4.
About object §4.1
Annotation object §3.1
AnnotationSet §4.
body §3.1
Body object §3.4
color §3.4
conformsTo §3.3.2.1
created §3.1
creator §3.1
Creator object §3.2
Fragment Selector object §3.3.2.1
highlight §3.4
items §4.
modified §3.1
motivation §3.1
refinedBy §3.3.2.4
selector §3.3
source §3.3
tags §3.4
target §3.1
Target object §3.3

[ANNOTATION-MODEL] defines the following:
- Annotation Collection
- Annotation object
- Body and Target
- CssSelector
- Fragment Selector
- refinedBy
- Selectors
- TextPositionSelector
[EPUB-34] defines the following:
- EPUB 3.4
- EPUB publications
- package document metadata
[I18N-GLOSSARY] defines the following:
- language tag
- localizable texts
- string direction
[JSON-LD11] defines the following:
- string internationalization

[annotation-model]: Web Annotation Data Model. Robert Sanderson; Paolo Ciccarese; Benjamin Young. W3C. 23 February 2017. W3C Recommendation. URL: https://www.w3.org/TR/annotation-model/
[ecma-404]: The JSON Data Interchange Format, 2nd edition. Ecma International. 1 December 2017. Standard. URL: https://www.ecma-international.org/wp-content/uploads/ECMA-404_2nd_edition_december_2017.pdf
[epub-34]: EPUB 3.4. Matt Garrish; Ivan Herman. W3C. 3 August 2026. CRD. URL: https://www.w3.org/TR/epub-34/
[ISO21320]: Document Container File - ISO/IEC 21320. ISO. 2015. International Standard. URL: https://www.iso.org/standard/60101.html
[json-ld11]: JSON-LD 1.1. Gregg Kellogg; Pierre-Antoine Champin; Dave Longley. W3C. 16 July 2020. W3C Recommendation. URL: https://www.w3.org/TR/json-ld11/
[json-schema]: JSON Schema: A Media Type for Describing JSON Documents. Austin Wright; Henry Andrews; Ben Hutton; Greg Dennis. Internet Engineering Task Force (IETF). 10 June 2022. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema
[media-frags]: Media Fragments URI 1.0 (basic). Raphaël Troncy; Erik Mannens; Silvia Pfeiffer; Davy Van Deursen. W3C. 25 September 2012. W3C Recommendation. URL: https://www.w3.org/TR/media-frags/
[RFC2119]: Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/info/rfc2119/
[rfc3236]: The 'application/xhtml+xml' Media Type. M. Baker; P. Stark. IETF. January 2002. Informational. URL: https://www.rfc-editor.org/info/rfc3236/
[RFC8174]: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/info/rfc8174/
[scroll-to-text-fragment]: URL Fragment Text Directives. Nick Burris; David Bokan. W3C. URL: https://wicg.github.io/scroll-to-text-fragment/
[svg11]: Scalable Vector Graphics (SVG) 1.1 (Second Edition). Erik Dahlström; Patrick Dengler; Anthony Grasso; Chris Lilley; Cameron McCormack; Doug Schepers; Jonathan Watt; Jon Ferraiolo; Jun Fujisawa; Dean Jackson et al. W3C. 16 August 2011. W3C Recommendation. URL: https://www.w3.org/TR/SVG11/
[url]: URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/
[zip]: .ZIP File Format Specification. 15 July 2020. Final. URL: https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT

[BCP47]: Tags for Identifying Languages. Addison Phillips; Mark Davis. IETF. September 2009. Best Current Practice. URL: https://www.rfc-editor.org/info/bcp47
[CSS3-selectors]: Selectors Level 3. Tantek Çelik; Elika Etemad; Daniel Glazman; Ian Hickson; Peter Linss; John Williams. W3C. 6 November 2018. W3C Recommendation. URL: https://www.w3.org/TR/selectors-3/
[dcterms]: DCMI Metadata Terms. DCMI Usage Board. DCMI. 20 January 2020. DCMI Recommendation. URL: https://www.dublincore.org/specifications/dublin-core/dcmi-terms/
[epub-anno-ucr]: EPUB Annotations Use Cases and Requirements. Laurent Le Meur. W3C. 24 February 2026. W3C Working Group Note. URL: https://www.w3.org/TR/epub-anno-ucr/
[html]: HTML Standard. Anne van Kesteren; Domenic Denicola; Dominic Farolino; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[i18n-glossary]: Internationalization Glossary. Richard Ishida; Addison Phillips. W3C. 17 October 2024. W3C Working Group Note. URL: https://www.w3.org/TR/i18n-glossary/
[rfc3987]: Internationalized Resource Identifiers (IRIs). M. Duerst; M. Suignard. IETF. January 2005. Proposed Standard. URL: https://www.rfc-editor.org/info/rfc3987/

EPUB Annotations 1.0

An interchange format for user notes, highlights, and bookmarks

Abstract

Status of This Document

1. Conformance

2. Introduction

2.1 Relationship to URL

3. Annotation

3.1 Annotation Object

Section

Describe the problem

Describe the fix or new feature you propose

3.2 Creator

3.3 Target

3.3.1 Source

3.3.2 Selector

3.3.2.1 Fragment Selector

3.3.2.2 CSS Selector

3.3.2.3 Text Position Selector

3.3.2.4 Refinement of a Selection

3.4 Body

4. Annotation Set

4.1 About

5. Serialization of an AnnotationSet

6. Sharing Annotation Sets

6.1 Detached annotations

6.2 Annotations embedded in EPUB

7. Expectations of Reading Systems behavior

7.1 Displaying and Filtering Annotations

7.2 Generating and Processing Selectors

7.3 Importing Annotations and Conflict Resolution

7.4 Exporting Annotations

7.5 Handling Unsupported Payload Types

7.6 Handling Fallbacks in top-level content documents

Section

Describe the problem

Describe the fix or new feature you propose

7.7 Color Mapping

8. JSON Schema

9. Internationalization Considerations

9.1 Localizable texts

9.1.1 Setting the default values

10. Privacy Considerations

11. Security Considerations

11.1 Plain Text Handling and Cross-Site Scripting (XSS)

11.2 External Resources and Network Security

11.3 Path Traversal and Local Access

11.4 Algorithmic Complexity and Denial of Service (DoS)

11.5 Spoofing and Data Integrity

A. Index

A.1 Terms defined by this specification

A.2 Terms defined by reference

B. Issue summary

C. References

C.1 Normative references

C.2 Informative references