Rewrite of the Reading System section#3006
Open
llemeurfr wants to merge 1 commit into
Open
Conversation
iherman
added
the
Spec-Annotations
iherman
approved these changes
May 26, 2026
iherman
left a comment
iherman
left a comment
Member
There was a problem hiding this comment.
Lots of minor editorial change proposal, nothing substantial. I believe this PR covers lots of grounds that we needed.
Food for thoughts: at some point we will have to have a security/privacy section, where we will be asked to enumarate a "threat model", ie, list the various possible security threats that arise. I believe our major threat source is the import mechanism: are there dangers that a maliciously created AnnotationSet might create problems. It strikes me that many of the scenarii in this new section might be looked at from that aspect, too.
But that is not a comment on this PR which is, after the editorial changes, merge-worthy...
Comment on lines
1254
to
1267
| <section> | ||
| <h3>Importing detached annotations</h3> | ||
|
|
||
| <p> | ||
| When a reading system imports detached annotations, it SHOULD check | ||
| whether those annotations are indeed for the publication being rendered. | ||
| Because there are no universally accepted identifiers for EPUB publications, this process involves some | ||
| heuristics that depend on the reading system, such as 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. | ||
| This process MAY require user interaction via the reading system's user interface. | ||
| In any case, information about the imported annotations SHOULD be provided to the user. | ||
| </p> | ||
| </section> |
Member
There was a problem hiding this comment.
Suggested change
If I read it well, this section has been copied into §6.3 of the new section; I believe we agreed to remove it.
|
|
||
| <section class="informative"> | ||
| <h1>Best Practices for Reading Systems</h1> | ||
| <h1>Reading Systems Behavior and Expectations</h1> |
Member
There was a problem hiding this comment.
Suggested change
| <h1>Reading Systems Behavior and Expectations</h1> | |
| <h1>Expectations of Reading Systems behavior</h1> |
I agree with the usage of "expectation". Maybe the rewrite sounds better, but a native speaker should be the final arbiter...
An aside: at some point, we will have to go through the whole text for a consistent usage of capitalization of terms ("reading system" or "Reading System"), of titles, etc...
| <section class="informative"> | ||
| <h1>Best Practices for Reading Systems</h1> | ||
| <h1>Reading Systems Behavior and Expectations</h1> | ||
| <p>While this specification primarily defines the serialization format for EPUB annotations, this section outlines the expected behaviors and capabilities of Reading Systems to ensure a consistent user experience and data interoperability across different environments.</p> |
Member
There was a problem hiding this comment.
Suggested change
| <p>While this specification primarily defines the serialization format for EPUB annotations, this section outlines the expected behaviors and capabilities of Reading Systems to ensure a consistent user experience and data interoperability across different environments.</p> | |
| <p>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.</p> |
| <h2>Displaying and Filtering Annotations</h2> | ||
| <p>To provide a useful user interface for managing annotations, Reading Systems are expected to:</p> | ||
| <ul> | ||
| <li><strong>Support metadata-based filtering:</strong> Allow users to filter the displayed annotations within a publication based on keys like <code>motivation</code> (e.g., distinguishing between a personal note and a bookmark), <code>creator</code>, <code>color</code>, <code>highlight</code>, and user-defined <code>tags</code>.</li> |
Member
There was a problem hiding this comment.
Suggested change
| <li><strong>Support metadata-based filtering:</strong> Allow users to filter the displayed annotations within a publication based on keys like <code>motivation</code> (e.g., distinguishing between a personal note and a bookmark), <code>creator</code>, <code>color</code>, <code>highlight</code>, and user-defined <code>tags</code>.</li> | |
| <li><strong>Support metadata-based filtering:</strong> Allow users to filter the displayed annotations within a publication based on keys like [=motivation=] (e.g., distinguishing between a personal note and a bookmark), [=creator=], [=color=], [=highlight=], and user-defined [=tags=].</li> |
(This respec trick puts a reference to the term where it has been defined.)
| <p>To provide a useful user interface for managing annotations, Reading Systems are expected to:</p> | ||
| <ul> | ||
| <li><strong>Support metadata-based filtering:</strong> Allow users to filter the displayed annotations within a publication based on keys like <code>motivation</code> (e.g., distinguishing between a personal note and a bookmark), <code>creator</code>, <code>color</code>, <code>highlight</code>, and user-defined <code>tags</code>.</li> | ||
| <li><strong>Handle multi-criteria filtering:</strong> Provide the capability to combine multiple filtering criteria simultaneously (e.g., filtering for annotations that are both tagged "review" and marked with a specific <code>color</code>) to help users manage large sets of annotations.</li> |
Member
There was a problem hiding this comment.
Suggested change
| <li><strong>Handle multi-criteria filtering:</strong> Provide the capability to combine multiple filtering criteria simultaneously (e.g., filtering for annotations that are both tagged "review" and marked with a specific <code>color</code>) to help users manage large sets of annotations.</li> | |
| <li><strong>Handle multi-criteria filtering:</strong> 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.</li> |
| <h2>Color Mapping and Fallbacks</h2> | ||
| <p>To ensure visual consistency across different reading environments, Reading Systems are expected to:</p> | ||
| <ul> | ||
| <li><strong>Map to a neutral default:</strong> If an annotation contains a <code>color</code> 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).</li> |
Member
There was a problem hiding this comment.
Suggested change
| <li><strong>Map to a neutral default:</strong> If an annotation contains a <code>color</code> 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).</li> | |
| <li><strong>Map to a neutral default:</strong> 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).</li> |
| <p>To ensure visual consistency across different reading environments, Reading Systems are expected to:</p> | ||
| <ul> | ||
| <li><strong>Map to a neutral default:</strong> If an annotation contains a <code>color</code> 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).</li> | ||
| <li><strong>Standardize colors on export:</strong> If the application uses proprietary or system-specific color names internally, map those colors to the closest matching standard value from the six enumerated profile colors (<code>pink</code>, <code>orange</code>, <code>yellow</code>, <code>green</code>, <code>blue</code>, <code>purple</code>) when exporting the data.</li> |
Member
There was a problem hiding this comment.
Suggested change
| <li><strong>Standardize colors on export:</strong> If the application uses proprietary or system-specific color names internally, map those colors to the closest matching standard value from the six enumerated profile colors (<code>pink</code>, <code>orange</code>, <code>yellow</code>, <code>green</code>, <code>blue</code>, <code>purple</code>) when exporting the data.</li> | |
| <li><strong>Standardize colors on export:</strong> 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.</li> |
I am just defensive: if, at any time, the color values change, then this paragraph remain valid. Better not to copy definitions...
| <ul> | ||
| <li><strong>Evaluate selectors by precision:</strong> Parse the array of Selectors in order of their precision (e.g., evaluating a <code>FragmentSelector</code> or <code>CssSelector</code> before falling back to broader text or range selectors).</li> | ||
| <li><strong>Implement robust fallback logic:</strong> If the primary or most precise selector fails to resolve because the underlying publication content has been modified, automatically attempt to resolve the alternative selectors provided in the array.</li> | ||
| <li><strong>Support core selector types:</strong> While Reading Systems have the freedom to implement only a subset of the selectors provided in this specification, they are expected to support the <code>CssSelector</code>, which is universally usable for both text and multimedia annotations.</li> |
Member
There was a problem hiding this comment.
Suggested change
| <li><strong>Support core selector types:</strong> While Reading Systems have the freedom to implement only a subset of the selectors provided in this specification, they are expected to support the <code>CssSelector</code>, which is universally usable for both text and multimedia annotations.</li> | |
| <li><strong>Support core selector types:</strong> While Reading Systems have the freedom to implement only a subset of the selectors provided in this specification, they are expected to support the <a data-cite="annotation-model#css-selector"><code>CssSelector</code>, which is universally usable for both text and multimedia annotations.</li> |
| <ul> | ||
| <li><strong>Facilitate publication mapping:</strong> 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.</li> | ||
| <li><strong>Alert and inform the user:</strong> Provide clear information about 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.</li> | ||
| <li><strong>Prevent data duplication:</strong> Use the unique <code>id</code> of each <code>Annotation</code> 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.</li> |
Member
There was a problem hiding this comment.
Suggested change
| <li><strong>Prevent data duplication:</strong> Use the unique <code>id</code> of each <code>Annotation</code> 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.</li> | |
| <li><strong>Prevent data duplication:</strong> Use the unique <code>id</code> of each <a href="#dfn-annotation-object"><code>Annotation</code></a> to detect collisions once the publication context is verified. If an incoming annotation shares an <code>id</code> 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.</li> |
| <h2>Exporting Annotations</h2> | ||
| <p>The <code>AnnotationSet</code> structure does not exist natively inside a reading application; it is a pure serialization artifact used during the export process. When generating this structure for export, Reading Systems are expected to:</p> | ||
| <ul> | ||
| <li><strong>Adhere to standard serialization layouts:</strong> Formulate the exported <code>AnnotationSet</code> precisely according to the JSON structures defined in Section 5, ensuring that detached files or embedded container elements are placed in their expected locations.</li> |
Member
There was a problem hiding this comment.
Suggested change
| <li><strong>Adhere to standard serialization layouts:</strong> Formulate the exported <code>AnnotationSet</code> precisely according to the JSON structures defined in Section 5, ensuring that detached files or embedded container elements are placed in their expected locations.</li> | |
| <li><strong>Adhere to standard serialization layouts:</strong> Create the [=AnnotationSet=] following the specification in section <a href="#serialization-of-an-annotationset"></a>, | |
| ensuring that detached files or embedded container elements are placed in their specified locations.</li> |
The change removes the explicit "Section 5" reference from the code, which is more future proof. However, if #3008 is accepted and merged, then these may change a bit. If that happens, there should be a merge into this branch and the reference to the section should change.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Following discussions in #2976 and #3001, and after the 21 April call, I rewrote the section previously named "Best Practices for Reading Systems".
The section is reframed as a set of Expectations (I preferred that over Use Cases because the latter is more about "this user makes this and expects that").
See: