-
Notifications
You must be signed in to change notification settings - Fork 125
ARIA annotations draft proposal
Annotations as they relate to ARIA:
- An annotation is visible information within a page, that is pointed via a relationship by the content that is related to it.
- The annotated content is the range of text or other object that points to the annotation.
- The annotation purpose is the general role that the annotation plays in the current data set, e.g. a comment vs. a footnote.
ARIA annotations are more limited than what can be expressed in the Web Annotations Data Model.
- They cannot point to information external to the web page
- They must point to additional information in the page (e.g. a simple "highlight" does not do this).
In addition, ARIA annotations do not contain as much information. It only contains what is necessary for the identified use cases.
For more information, please see the Addendum on mapping Web Annotations Data Model to HTML/ARIA.
- Document editor
- Code editor
- Published content
- AT user issues command to navigate to previous/next annotated content (e.g. next commented text)
- AT user issues command to navigate to previous/next annotation (e.g. next comment)
- AT user issues one of the above commands, but filtered by annotation purpose (e.g. footnotes only)
- AT user issues command to navigate from annotation to annotated content, or vice-versa
- Screen reader provides viewing options for reading annotations inline, where the annotation purpose is abbreviated, e.g. "comment" becomes "*ct"
-
aria-details (required, IDREF)
- Goes on the annotated content, and points to the in-page annotation.
- Example:
<span aria-details="comments">This is commented text</span>
-
role (optional, NMTOKENS)
- Goes on the annotation, describing the annotation purpose. See below for a list of roles and more details.
- Example:
<div role="annotation-comment"> - As is always the case, multiple roles are supported: if more than one role is provided then the first recognized role may be mapped through accessibility APIs. The most important or specific role should always go first. For example,
<div role="aria-suggestion aria-comment group">would indicate that there is a suggestion with comments, but some APIs may only expose it as a "suggestion".
-
<ins>/<del>(required for the "revision" and "suggestion" annotation purposes)- Provided as children of the annotated content, and define a past change or proposed future change to the document. TBD: Alternatively, when ARIA provides roles for insertion and deletion, the role attribute could be used instead.
- Example:
<p>Everyone is encouraged to bring a <span aria-details="suggestion-info-1"><del>side dish</del><ins>beverage</ins></span> to share.</p>. - Ordering: the ARIA spec should define whether the order is important for these 1-2 children. I suggest the AT should handle all permutations in the ordering.
In addition, the following markup may be helpful but is not really part of the annotations spec:
-
aria-label/aria-labelledby/aria-describedby (optional)
- If this is found on the annotation, it could provides a useful label or description for the annotation, that could be presented by a screen reader in a mode where the user wanted to understand more about the annotations in context but the annotations themselves would be too long.
These go on the annotation, not the annotated content.
All annotation- prefixed roles would inherit from an abstract role of "annotation", which would inherit from "structure". If the role is not provided, then the annotation is simply treated as a description, as it would already be via aria-details usage.
- annotation-attribution— authoring information for the annotated content. TBD: Note from @mck, we may want to choose a better name as this name may ultimately just be used by screen readers and most users might not know what to make of it.
- annotation-comment— one or more comments, or a comment thread
- annotation-description — generic description. This is also the default if the annotation purpose is unspecified.
- annotation-revision — this is a historical change that has already been accepted. The source annotated content will contain 1-2 children for the insertion and/or deletion.
- annotation-suggestion — proposed edit. The source annotation will contain 1-2 children for the proposed insertion and/or deletion.
- annotation-presence — similar to attribution, but relates to editing that is happening right now. For example, "Mr. Smith is editing nearby".
- doc-footnote, doc-endnote, doc-biblioentry, or annotation-reference for footnotes, endnotes, bibliography entries, or generalized references. When using DPUB roles, the annotated content will be the referencing number and should also receive a role of doc-noteref, doc-glossref, doc-biblioref, etc. TBD: there is no doc-glossentry to match doc-glossref, should there be? There is doc-glossary as a container but no role for the individual glossary entries.
Use the singular form: for consistency, all of the annotation purposes are in the singular form of the word, even though in some cases the plural could have made sense, as in "comment" where there may be multiple comments.
- highlight — this does not fit the proposed definition of an annotation in that it does not point to additional info. Therefore, ARIA WG should consider adding something like role=mark (would need to be added) or em/strong for role parity
- error — in code in code editor: use the already supported aria-invalid="true" + aria-errormessage=id
- warning— in code editor: may want to add aria-invalid="warning" as possible value (and like error, can use aria-errormessage=id)
- bookmark — would need more info on this use case in order to support it
- breakpoint— does not always come with additional visible information, so it would be difficult to shoehorn into this use case. For this one, perhaps a role="mark" or a new role="breakpoint" could be used, along with aria-describedby. Or, a visible button could be used on the line with the breakpoint, that is labelled as a breakpoint button.
- UI Automation has built-in support for annotations — note that a perfect 1 to 1 mapping is not expected here. For example, a grammar error is an annotation in UIA, but in ARIA is aria-invalid="grammar". An important difference with UIA annotations is that ARIA annotations always link to visible in-page content.
- Most of the markup is reused — there are already known ways for exposing aria-details, aria-label, aria-labelledby, aria-describedby,
<ins>and<del>. - For aria-annotation, this should be exposed as an object attribute called "annotation" in ATK/IA2
An important use case is to convert annotation data from the Web Annotations Data Model (in JSON format) into accessible markup in a document, with the goal of enabling AT support. The following are non-normative suggestions for accomplishing this.
Translating a “commenting” motivation in the data model to the appropriate ARIA and HTML markup:
<div id=”comment-thread-1” role=”annotation-comment”>
<h1>Comment by Ruff Finkledog</h1>
<p>Wouldn’t it be simpler to list the cooperative cats?</p>
</div>
This example is useful for the "highlighting" motivation.
<p>The word <mark>cat</mark> is highlighted</p>
This example is useful for the "identifying" motivation.
<p>A <a href="https://en.wikipedia.org/wiki/Cat">cat</a> is one of our favorite quirky pets.</p>
|
Web Annotations Data Model Concept |
Proposed additional markup on annotation |
Proposed markup on annotated content |
Description |
|
Assessing motivation |
|
|
The motivation for when the user intends to assess the target resource in some way, rather than simply make a comment about it. For example to write a review or assessment of a book, assess the quality of a dataset, or provide an assessment of a student's work. |
|
Bookmarking motivation |
none |
|
The motivation for when the user intends to create a bookmark to the Target or part thereof. For example an Annotation that bookmarks the point in a text where the reader finished reading. |
|
Classifying motivation |
|
|
The motivation for when the user intends to classify the Target as something. For example to classify an image as a portrait. |
|
Commenting motivation |
|
|
The motivation for when the user intends to comment about the Target. For example to provide a commentary about a particular PDF document. |
|
Describing motivation |
|
|
The motivation for when the user intends to describe the Target, as opposed to (for example) a comment about it. For example describing the above PDF's contents, rather than commenting on their accuracy. |
|
Editing motivation |
|
Must also have <ins>, <del> child or both |
The motivation for when the user intends to request a change or edit to the Target resource. For example an Annotation that requests a typo to be corrected. |
|
Highlighting motivation |
none |
Use |
The motivation for when the user intends to highlight the Target resource or segment of it. For example to draw attention to the selected text that the annotator disagrees with. |
|
Identifying motivation |
none |
|
The motivation for when the user intends to assign an identity to the Target. For example to associate the IRI that identifies a city with a mention of the city in a web page. |
|
Linking motivation |
none |
|
The motivation for when the user intends to link to a resource related to the Target. |
|
Moderating motivation |
|
|
The motivation for when the user intends to assign some value or quality to the Target. For example annotating an Annotation to moderate it up in a trust network or threaded discussion. |
|
Questioning motivation |
|
|
The motivation for when the user intends to ask a question about the Target. For example, to ask for assistance with a particular section of text, or question its veracity. |
|
Replying motivation |
|
|
The motivation for when the user intends to reply to a previous statement, either an Annotation or another resource. For example providing the assistance requested in the above. |
|
Tagging motivation |
|
|
The motivation for when the user intends to associate a tag with the Target. |
|
Attribution from provenance chunk |
|
|
Authoring information for the annotated content |
|
Does not currently exist in Web Annotations Data Model |
|
Must also have |
This is a historical change that has already been accepted. The source annotated content will contain 1-2 children for the insertion and/or deletion |
|
Does not currently exist in Web Annotations Data Model |
|
|
|
|
Does not currently exist in Web Annotations Data Model |
|
|
In-page links for footnotes, endnotes, bibliographical information in a document |