ARIA Annotations

W3C Editor's Draft

This version:
https://w3c.github.io/annotation-aria/
Latest published version:
https://www.w3.org/TR/annotation-aria/
Latest editor's draft:
https://w3c.github.io/annotation-aria/
Editors:
Michael Cooper (W3C)
Aaron Leventhal (Google, Inc.)
(John Wiley & Sons, Inc.)
Participate:
GitHub w3c/annotation-aria
File a bug
Commit history
Pull requests

Abstract

ARIA Annotations provides markup for accessible, in-page annotations. This specification describes the mechanism for signaling that content has been annotated, for what purpose, and where to find the related additional content.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This is an unofficial proposal.

This document was published by the Accessible Rich Internet Applications Working Group as an Editor's Draft.

GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-aria@w3.org (archives).

Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2019 W3C Process Document.

1. Introduction

Annotations provide additional content about the primary content of a document. Their uses vary from commentary, to suggested edits, to attribution, and even noting the presence of other readers.

Much of the necessary building blocks already exist with other ARIA specifications. This specification provides the minimal additions needed to improve the reading experience of annotated content when consumed via assistive technology.

Additionally, this specification takes steps to use consistent terminology and modeling from past annotation specifications at the W3C, most notably the Web Annotation Data Model [annotation-model].

1.1 Definitions

The following terminology is informed by the Web Annotation Data Model [annotation-model] specification. You can read more about the underlying conceptual model in that introduction.

Issue
@bigbluehat: perhaps a similar graph (as the one in the WADM) showing the relationship between the parts would be helpful here.
annotation
An annotation is the combination of annotated content and its related annotation body.
annotated content
The annotated content is the range of text or other object which the annotation body is "about".
Note: In the Web Annotations Data Model, this is known as the annotation target. However, because the term "target" has a specific meaning in accessibility APIs as the end (and not beginning) of a relation, the term annotated content is preferred here, in order to avoid confusion with the actual directionality of aria-details in ARIA annotation markup.
annotation body
The annotation body is visible information within a page which is connected to annotated content for a related purpose.
annotation purpose
The annotation purpose is the role the annotation body plays in relation to the annotated content (e.g. commentary vs. a footnote).

1.2 How do ARIA annotations relate to the Web Annotations Data Model?

ARIA annotations are deliberatly more limited than what can be expressed within a Web Annotations Data Model [annotation-model] document. For example:

In addition, ARIA annotations do not contain as much information as they only contain what is necessary to move between the primary annotated content, and the additional content.

Authors desiring to expand the expresiveness of their markup beyond what is provided by ARIA annotations should consult the Embedding Web Annotations in HTML Note [annotation-html].

For further information, please see the Web Annotation Data Model correlations below.

2. Use Cases

2.1 Web Content

2.2 Assistive Technology

3. Annotation Markup

ARIA annotations are built from existing ARIA attributes. This specification does introduce new role values to distinguish the purpose of annotated content from among each other and from among other content within the current page.

3.1 Basic expression

Annotated content markup MUST use the aria-details attribute which MUST contain the IDREF of an annotation body which exists in the current web page.

Any HTML tag MAY be used. It is not required to use the role attribute. However, when a visible highlight is intended, authors SHOULD prefer using an element such as <mark> over a more semantically generic and visually invisible element such as <span>.

The aria-details attribute MUST reference an element within the current Web page which contains the annotation body.

<p><mark aria-details="comment-123">The proposal</mark> contains...</p>
...
<div id="comment-123">I think this is great!</div>

Use of the aria-details attribute MUST follow any additional requirements expressed in the Accessible Rich Internet Applications [wai-aria-1.2] specification.

3.2 Stating a purpose

The annotation body contains the commentary, suggestions, or secondary content about the annotated content.

The role on the annotation body describes the purpose or intent (i.e. the annotation purpose) of the annotation body. See below for a list of available roles meant for use in ARIA annotations.

<p><mark aria-details="comment-123">The proposal</mark> contains...</p>
...
<div id="comment-123" role="annotation-commentary">I think this is great!</div>

Multiple role attribute values are supported. If more than one role value is provided then the first recognized role MAY be mapped through accessibility APIs. Consequently, annotation authors SHOULD place the most important (or specific) role first.

For example, the following would indicate that there is a suggestion with comments, but some APIs may only expose it as a "suggestion":

<p><mark aria-details="suggestion-123">The proposal</mark> contains...</p>
...
<div id="suggestion-123" role="annotation-suggestion annotation-commentary group">
  I think this is great! However, I think you might want to change "proposal"
  to "recommendation."
</div>

3.2.1 Roles for annotation purposes

The purpose of an annotation by placing a role attribute on the annotation body, not the annotated content.

All annotation- prefixed role values inherit from an abstract role of annotation, which inherits from structure. If the role attribute is not provided, then the annotation is simply treated as a description.

Below is an alphabetical list of WAI-ARIA roles to be used by rich internet application authors.

annotation
A renderable structural annotation containment unit in a document or application.
annotation-attribution
Authoring information for the annotated content.
annotation-commentary
One or more comments, or a comment thread.
annotation-description
Generic description. This is the default if the annotation purpose is unspecified.
annotation-revision
An historical change that has already been accepted. The source annotated content MUST contain 1-2 children for the insertion and/or deletion.
annotation-suggestion
A proposed edit. The source annotated content MUST 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".
annotation (abstract role)

A renderable structural annotation containment unit in a document or application.

Note

annotation is an abstract role used for the ontology. Authors should not use this role in content.

Characteristics:
Characteristic Value
Is Abstract: True
Superclass Role: section
Subclass Roles:
Inherited States and Properties:
Name From: author
Accessible Name Required: False
annotation-attribution (role)

Authoring information for the annotated content.

...
Characteristics:
Characteristic Value
Superclass Role: annotation
Inherited States and Properties:
Name From: author
Accessible Name Required: False
Issue 4: Consider a different name for `annotation-attribution`

From @mcking65:

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.

Issue 5: Remove `annotation-attribution` in favor of using `annotation-revision`

From @aleventhal:

recommend we make this redundant with annotation-revision, and remove this one.

annotation-commentary (role)

One or more comments, or a comment thread.

...
Characteristics:
Characteristic Value
Superclass Role: annotation
Inherited States and Properties:
Name From: author
Accessible Name Required: False
annotation-description (role)

Generic description. This is the default if the annotation purpose is unspecified.

...
Characteristics:
Characteristic Value
Superclass Role: annotation
Inherited States and Properties:
Name From: author
Accessible Name Required: False
Issue 6: Consider removing `annotation-description` and making that the default "purpose"

From @aleventhal:

rather than add an extra role here, how about the author simply not use any of the other annotation roles.

annotation-revision (role)

An historical change that has already been accepted. The source annotated content MUST contain 1-2 children for the insertion and/or deletion.

...
Characteristics:
Characteristic Value
Superclass Role: annotation
Inherited States and Properties:
Name From: author
Accessible Name Required: False
annotation-suggestion (role)

A proposed edit. The source annotated content MUST contain 1-2 children for the proposed insertion and/or deletion.

...
Characteristics:
Characteristic Value
Superclass Role: annotation
Inherited States and Properties:
Name From: author
Accessible Name Required: False
annotation-presence (role)

Similar to attribution, but relates to editing that is happening right now. For example, "Mr. Smith is editing nearby".

...
Characteristics:
Characteristic Value
Superclass Role: annotation
Inherited States and Properties:
Name From: author
Accessible Name Required: False
  • doc-footnote/doc-endnote for footnotes and endnotes. When using DPUB roles, the annotated content will be the referencing note number. The author may choose to leave out the doc-noteref role on the annotated content, as that will be exposed as a link to ATs (see [DPUB-AAM-1.0]), and it may not be a link. In addition, the fact that it is a note reference number is implied by the relation with the annotation body, which will have the doc-footnote or doc-endnote role.

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 "suggestion" where there may be multiple suggestions.

3.3 Expressing editorial activities

Annotations motivated by expressing a revision to the annotated content or which are providing suggestions to that content come with an additional requirement to convey that revision or suggestion.

The annotated content of such a change-related annotation MUST contain at least one HTML <ins> or <del> tag or at least one HTML tag with a role value of either insertion or deletion defined in [wai-aria-1.2].

If a replacement to the annotated content is being requested, authors MUST provide both an <ins> and a <del> tag together or two HTML tags one with role="insertion" and the other with role="deletion".

Each combination of an <ins> and a <del> tag pair (or their equivalent expressed via insertion/deletion roles) SHOULD be authored as separate annotated content (i.e. no more than one of each per grouping).

Example 10: suggestion using <ins> and <del>
<p>Everyone is encouraged to bring a
<span aria-details="suggestion-info-1"><del>side dish</del><ins>beverage</ins></span>
to share.</p>
Example 11: suggestion using insertion and deletion roles
<p>Cats are so funny:
<span aria-details="suggestion-info-1"><span role="deletion"><img src="dog.jpg"></span><span role="insertion"><img src="cat.jpg"></span></span>
Pretty cute, right?!</p>

Assistive Technology SHOULD handle all permutations of the ordering of <ins> and <del> when processing edits.

Note
In future, the [wai-aria-1.2] specification may define whether the order of <ins> and <del> are important.
Issue 7: Should `annotation-suggestion`/`annotation-revision` processing ignore additional markup?

Right now, we define (somewhat implicitly...) how <ins>/<del> could be processed by AT into actual edits in the main text (i.e. replacing the annotated content following the logic expressed via <ins> and/or <del>).

Should we also add something about how to handle any other markup? I'd suggest we state that it should be thrown out entirely--but want to make sure that's what would be expected here from an AT perspective (and that there aren't hidden "gotchas" I've not yet thought about).

To distinguish between revisions (past edits) and suggestions (future edits), an annotation purpose can be expressed by placing the appropriate role value on the related annotation body.

<p>Everyone is encouraged to bring a
<span aria-details="suggestion-info-1"><del>side dish</del><ins>beverage</ins></span>
to share.</p>
<!-- later in the document... -->
<div id="suggestion-info-1" role="annotation-suggestion">
Change of plans! Thanks updating this, Aaron
</div>

3.4 Further annotation labeling

(optional)
Issue
@bigbluehat update this to be non-normitave/description/examplary

In addition, this markup may be helpful, but is not really part of the annotations spec:

4. Web Annotation Data Model correlations

An important use case is to convert annotation data from the Web Annotation Data Model [annotation-model] (typically in JSON format) into accessible content, with the goal of enabling AT support. The following are non-normative suggestions for accomplishing this.

4.1 Purpose to Role Mapping Table

Web Annotation motivation/purpose Additional markup on the annotation body Markup on the annotated content Description
Assessing role="annotation-commentary" aria-details=[id] 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 none

aria-details=[id]

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

role="annotation-description" aria-details=[id] (if classifications visible in page) The motivation for when the user intends to classify the Target as something. For example to classify an image as a portrait.
Commenting role="annotation-commentary" aria-details=[id] The motivation for when the user intends to comment about the Target. For example to provide a commentary about a particular PDF document.
Describing role="annotation-description" aria-details=[id] 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 role="annotation-suggestion"

aria-details=[id]

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 none Use <mark> or appropriate ARIA role from role parity work once available 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 none <a href=[IRI]>external link</a> 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 none aria-details=[id] The motivation for when the user intends to link to a resource related to the Target.
Moderating role="annotation-commentary" aria-details=[id] 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 role="annotation-commentary" aria-details=[id] 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 role="annotation-commentary" aria-details=[id] 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 role="note", e.g. <div role="note">Tags: cats, pets</div> aria-details=[id] (if tags are visible in content) The motivation for when the user intends to associate a tag with the Target.
Attribution from provenance chunk role="annotation-attribution" aria-details=[id] (if attribution is visible in content) Authoring information for the annotated content
Does not currently exist in Web Annotations Data Model role="annotation-revision"

aria-details=[id]

Must also have <ins>, <del> child or both

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 role="annotation-presence" aria-details=[id]
Does not currently exist in Web Annotations Data Model role="doc-footnote" | role="doc-endnote" | role="doc-biblioentry" aria-details In-page links for footnotes, endnotes, bibliographical information in a document

5. Platform Accessibility mappings

Issue
@bigbluehat: does "aria-annotation" here mean this spec? It seems to (vs. an attribute or value)

A. Rejected annotation purposes

Issue
@bigbluehat: move this to an appendix? remove it? Kind of nice to know what we didn't do and why

For now, the following annotation purposes have not been assigned new roles:

Issue
[TBD] @aleventhal: Suggest that the author can use <mark aria-label="Bookmark name"> for a good experience.
Issue
[TBD] @aleventhal: For this one, perhaps a <mark> or role="mark" or a new role="breakpoint" could be used, along with aria-label. Or, a visible button could be used on the line with the breakpoint, that is labelled as a breakpoint button.

B. References

B.1 Informative references

[annotation-html]
Embedding Web Annotations in HTML. Timothy Cole; Sarven Capadisli; Benjamin Young; Ivan Herman. W3C. 23 February 2017. W3C Note. URL: https://www.w3.org/TR/annotation-html/
[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/
[DPUB-AAM-1.0]
Digital Publishing Accessibility API Mappings. Richard Schwerdtfeger; Joanmarie Diggs. W3C. 14 December 2017. W3C Recommendation. URL: https://www.w3.org/TR/dpub-aam-1.0/
[wai-aria-1.2]
Accessible Rich Internet Applications (WAI-ARIA) 1.2. Joanmarie Diggs; Shane McCarron; James Nurthen; Michael Cooper; Richard Schwerdtfeger; James Craig. W3C. 18 December 2018. W3C Working Draft. URL: https://www.w3.org/TR/wai-aria-1.2/