Terminology

This specification uses terminology defined in EPUB 3.3 [[epub-33]].

It also defines the following terms:

standard EPUB CFI

A publication-level EPUB CFI links into an EPUB publication. The path preceding the EPUB CFI references the location of the EPUB publication.

intra-publication EPUB CFI

An intra-publication EPUB CFI allows one EPUB content document to reference another within the same Rendition of an EPUB publication. The path preceding the EPUB CFI references the current Rendition's package document.

Refer to Intra-Publication CFIs for more information.

Syntax

A Canonical Fragment Identifier (CFI) consists of an initial sequence epubcfi that identifies this particular reference method, and a parenthesized path or range. A path is built up as a sequence of structural steps to reference a location. A range is a path followed by two local (or relative) paths that identify the start and end of the range.

Steps are denoted by the forward slash character (/), and are used to traverse XML content. The last step in a CFI path represents a location within a document, either structural (XML element), textual (character data), or aural-visual (image, audio, or video media). Such terminating steps MAY be complemented by an OPTIONAL "offset", which denotes a particular character position, temporal or spatial fragment.

Substrings in brackets are extensible assertions that improve the robustness of traversing paths and migrating them from one revision of the document to another. These assertions preserve additional information about traversed elements of the document, which makes it possible to recover intended location even after some modifications are made to the EPUB publication.

Although the value definition in the syntax above allows any a sequence of characters, a circumflex (^) MUST be used to escape the following characters to ensure their presence does not interfere with parsing:

• brackets ([,])

• circumflex (^)

• comma (,)

• parentheses ((,))

• semicolon (;)

The following rules apply to the use of numbers and integers within the path or range:

• leading zeros are not allowed for numbers or integers (to ensure uniqueness);

• trailing zeros are not allowed in the fractional part of a number;

• zero MUST be represented as the integer 0;

• numbers in the range 1 > N > 0 MUST have a leading 0.;

• integral numbers MUST be represented as integers.

Character escaping

As described in Syntax, the EPUB CFI grammar contains characters that have a special purpose as delimiters within a fragment identifier expression. These characters MUST be escaped using the circumflex '^' character when not intended for use as delimiters, so that they can appear within the EPUB CFI data without being mistaken for delimiters. Depending on the usage context of such EPUB CFI, further character escaping MAY be necessary in order to ensure that all potentially-conflicting text tokens are encoded correctly.

• IRI and URI references:

  • The EPUB CFI (fragment identifier) scheme is designed to be used within URI and IRI references. The [[rfc3986]] specification defines a number of "reserved" characters that have a specific purpose as delimiters, and which MAY need to be escaped in cases when they would otherwise conflict with the syntactical structure of the URI/IRI reference. The character used for escaping is the percent sign '%', and escapable characters get percent-encoded. For example, the percent character itself becomes "%25" when it gets escaped (note the difference with EPUB CFI's circumflex '^', which gets escaped using a double character '^^').

  • Unlike IRI references, URI references require unicode characters to be ASCII-encoded. Although the EPUB specification itself is based on IRIs (i.e. authors and production tools are expected to use IRIs), some systems or APIs might only support URIs. As a result, implementors MAY still need too handle the conversion of IRI to URI references, as defined in [[rfc3987]]. Disallowed characters are escaped as follows:

    • Each disallowed character is converted to UTF-8 [[rfc2279]] as one or more bytes. The disallowed characters in URI references include all non-ASCII characters, plus the excluded characters listed in Section 2.4 of [[rfc2396]], except for the number sign '#' and percent sign '%' and the square bracket characters re-allowed in [[rfc2732]].

      The resulting bytes are escaped with the URI escaping mechanism (that is, converted to '%HH', where HH is the hexadecimal notation of the byte value).

      The original character is replaced by the resulting character sequence.

• (X)HTML context:

  IRI references are designed to be used in the various types of documents that EPUB publications comprise. XML and (X)HTML represent yet another insertion context that requires specific character escaping rules. For example, double quote characters or angle brackets conflict with significant delimiters in the markup syntax, and MUST therefore be escaped using the &xxx; special sequence (character reference).

When multiple layers of character escaping are applied to escape or unescape an EPUB CFI, they MUST be applied in reverse order to revert back to the original form. For example, [ EPUB-CFI -> IRI -> (X)HTML ] becomes [ (X)HTML -> IRI -> EPUB-CFI ]

Path resolution

The process of resolving an EPUB CFI to a location within an EPUB publication begins with the root package element of the package document. Each step in the CFI is then processed one by one, left to right, applying the rules defined in the following subsections.

Sorting rules

In order to sort or compute relative locations of multiple EPUB CFIs referencing the same EPUB publication, the following rules MUST be applied:

1. The EPUB CFI scheme data MUST be in unescaped form, as per the rules described in Character Escaping.

2. all bracketed assertions are removed (ignored) entirely;

3. steps that come earlier in the sequence are more important;

4. XML elements, references to chunks of XML character data, character offsets and temporal positions are sorted in natural order;

5. the y position is more important than x;

6. omitted spatial position precedes all other spatial positions;

7. omitted temporal position precedes all other temporal positions;

8. temporal position is more important than spatial;

9. different step types come in the following order from least important to most important: character offset (:), child (/), temporal-spatial (~ or @), reference/indirect (!).

Intra-publication CFIs

An EPUB CFI can be used to reference content inside the container. This kind of referencing can be achieved by specifying a reference to the package document followed by a CFI, which MUST be resolved starting from the root package element.

For example, using the package document in the previous example, a reference to the last location in chapter01.xhtml might be written as follows:

Simple ranges

EPUB CFIs allow the expression of simple ranges extending from a start location to an end location. A range MUST be expressed as a triple of parent path (P), start subpath (S) and end subpath (E), or of the form:

The parent path MUST not be empty, and MUST end at a step that is common for resolving both the path of the start and end locations of the range, and each start and end subpath MUST resolve to a location in non-decreasing order in the document.

To determine the start and end locations of the range, the start and end subpaths MUST be concatenated to the parent path to create the start location path (PS) and end location path (PE). The parent path SHOULD include the deepest possible common path leading to both the start and end path (in other words, the start and end location SHOULD NOT contain a common path). The start location MAY be empty, to avoid repetition of a common path in cases where the end location is situated within the subtree rooted at the start location.

Using the sample documents above, the following range would represents the text from the second y in yyy up to (and including) digit 3:

Ranges MUST be compared according to their PS, then PE, components. The start and end locations SHOULD reference points in the document that have the same "nature", that is to say elements and character offsets (document structure), temporal offsets (timed media), spatial offsets (visual media), or the combined temporal-spatial offsets. In the case of temporal offsets, the start and end locations SHOULD reference the same timed media. In the case of spatial offsets, the start and end locations SHOULD reference the same visual media. This specification does not define expected behaviors, such as how the combination of two spatial offsets (i.e., start and end locations within a visual media) is to be interpreted by processing agents, including production tools and reading systems.

It is not valid to use a path to an element as a shorthand for the range from the beginning to the end of the element. Single path notation always denotes a location point, and range is represented by the notation described above. There is no special step to produce a reference to the end of an element, as that would make sorting impossible without consulting the content of the document.

If range is used where single location is expected by the context, the start location MUST be used.

Side-bias parameters MUST NOT be used for ranges; the start of a range is implicitly attached to the content after the start location and the end is implicitly attached to the content before the end location.

Intended target location correction

As an EPUB publication can be updated, corrected or otherwise altered over time, it is useful to be able to derive an EPUB CFI for the modified document from one that targeted a previous version. This specification provides two mechanisms to detect and adapt to content changes that impact CFIs: IDs [[xml]] and text location assertions.

When a reading system is processing a CFI, it SHOULD check the correctness of any encountered assertions. For example, given the path /6/4[chap01ref]!…, the reading system SHOULD verify that the element has the ID matching chap01ref when processing element 4 (for this example, an itemref in the spine). If not, the reading system SHOULD locate the ID chap01ref within the document and correct the CFI (e.g., if a new itemref was inserted before the chap01ref itemref, the desired element number would now be 6 and the corrected CFI would be /6/6[chap01ref]!…). Likewise, text location assertions SHOULD be used to check referenced target locations, and used to derive a corrected CFI that targets the desired text location.

If one of the assertions fails during processing, and a corrected CFI can not be derived (the ID is not found in the document, or text matches could not be found), the CFI MUST be considered an invalid reference. In cases where a reading system cannot check for correctness (e.g., document-resident XML IDs are not available at CFI processing time), a reading system MUST ignore the CFI assertions.

This notion of correcting CFIs can lead to circumstances where two different CFIs point to the same location (i.e., the "stale" CFI, pre-correction, and the corrected CFI). The corrected CFI SHOULD be used where possible. A reading system and any surrounding content management system SHOULD attempt to replace stale CFIs with their corrected versions where possible.