ARIA Annotations

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.

3. Annotation Markup

ARIA Annotations are built from the existing ARIA attributes: aria-details and role. This specification introduces new role values to distinguish the purpose of annotated content from among each other and from among other content within the current page. These distinctly expressed purposes may be used by AT to provide additional filtering or experience affordances when rendering the annotations.

3.1 Basic expression

The Accessible Rich Internet Applications [wai-aria-1.2] specification explains the use of aria-details as "[identifying] the element that provides a detailed, extended description for the object." ARIA Annotations build on that foundation and provide further contextual meaning via the use of role values specific to annotation use cases.

Consequently, the requirements for a minimal ARIA Annotation are no different than a simple use of aria-details.

Example 1

<p><mark aria-details="comment-123">The proposal</mark> contains...</p>
<!-- ...elsewhere in the document... -->
<div id="comment-123">This proposal is great!</div>

Therefore, Annotated content markup MUST use the aria-details attribute which MUST contain the IDREF of an annotation body which MUST exist in the current web page. It is not required to use a role attribute.

Any element MAY be used. 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>.

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 description, commentary, suggestions, or secondary content related to the annotated content. The contents of the annotation body is considered a description by default. The addition of a role to the annotation body describes the purpose or intent (i.e. the annotation purpose) of the annotation body beyond simple description.

For example, the following annotation body states that its purpose is commentary through the use of the role value annotation-commentary.

Example 2

<p><mark aria-details="comment-123">The proposal</mark> contains...</p>
<!-- ...elsewhere in the document... -->
<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.

The following markup states that there is a suggestion with comments, but some APIs may only expose it as a "suggestion":

Example 3

<p><mark aria-details="suggestion-123">The proposal</mark> contains...</p>
<!-- ...elsewhere in the document... -->
<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-presence: Similar to attribution, but relates to editing that is happening right now.
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.
doc-endnote: One of a collection of notes that occur at the end of a work, or a section within it, that provides additional context to a referenced passage of text.
doc-footnote: Ancillary information, such as a citation or commentary, that provides additional context to a referenced passage of text.

`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:	`annotation-attribution` `annotation-commentary` `annotation-presence` `annotation-revision` `annotation-suggestion`
Inherited States and Properties:	`aria-atomic` `aria-busy (state)` `aria-controls` `aria-current (state)` `aria-describedby` `aria-details` `aria-disabled (state)` `aria-dropeffect` `aria-errormessage` `aria-expanded (state)` `aria-flowto` `aria-grabbed (state)` `aria-haspopup` `aria-hidden (state)` `aria-invalid (state)` `aria-keyshortcuts` `aria-label` `aria-labelledby` `aria-live` `aria-owns` `aria-relevant` `aria-roledescription`
Name From:	author
Accessible Name Required:	False

`annotation-attribution` (role)

Authoring information for the annotated content.

Example 4

Benjamin Franklin is oft quoted as saying,
<p><mark aria-details="quote-123">"A penny saved is a penny earned"</mark>
when in fact, he said, <mark aria="details="quote-456">"A penny saved is twopence dear"</mark></p>
<!-- ...elsewhere in the document... -->
<div id="quote-123" role="annotation-attribution">Commonly misattributed to Benjamin Franklin</div>
<div id="quote-456" role="annotation-attribution">Benjamin Franklin</div>

Characteristics:
Characteristic	Value
Superclass Role:	`annotation`
Inherited States and Properties:	`aria-atomic` `aria-busy (state)` `aria-controls` `aria-current (state)` `aria-describedby` `aria-details` `aria-disabled (state)` `aria-dropeffect` `aria-errormessage` `aria-expanded (state)` `aria-flowto` `aria-grabbed (state)` `aria-haspopup` `aria-hidden (state)` `aria-invalid (state)` `aria-keyshortcuts` `aria-label` `aria-labelledby` `aria-live` `aria-owns` `aria-relevant` `aria-roledescription`
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.

Example 5

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

Characteristics:
Characteristic	Value
Superclass Role:	`annotation`
Inherited States and Properties:	`aria-atomic` `aria-busy (state)` `aria-controls` `aria-current (state)` `aria-describedby` `aria-details` `aria-disabled (state)` `aria-dropeffect` `aria-errormessage` `aria-expanded (state)` `aria-flowto` `aria-grabbed (state)` `aria-haspopup` `aria-hidden (state)` `aria-invalid (state)` `aria-keyshortcuts` `aria-label` `aria-labelledby` `aria-live` `aria-owns` `aria-relevant` `aria-roledescription`
Name From:	author
Accessible Name Required:	False

`annotation-presence` (role)

Similar to attribution, but relates to editing that is happening right now.

Example 6

<h1>Quotes from The Matrix</h1>
<blockquote>I know you're out there. I can feel you now. I know that
you're afraid...<mark aria-details="precence-123"></mark></p>
you're afraid of us. You're afraid of change.</blockquote>
<!-- ...elsewhere in the document... -->
<div id="precence-123" role="annotation-presence">Mr. Smith is editing nearby.</div>

Issue

@bigbluehat: are there accessibility concerns with empty annotated content markup (see above)? Per ARIA: "Authors SHOULD ensure the element referenced by aria-details is visible to all users."

Characteristics:
Characteristic	Value
Superclass Role:	`annotation`
Inherited States and Properties:	`aria-atomic` `aria-busy (state)` `aria-controls` `aria-current (state)` `aria-describedby` `aria-details` `aria-disabled (state)` `aria-dropeffect` `aria-errormessage` `aria-expanded (state)` `aria-flowto` `aria-grabbed (state)` `aria-haspopup` `aria-hidden (state)` `aria-invalid (state)` `aria-keyshortcuts` `aria-label` `aria-labelledby` `aria-live` `aria-owns` `aria-relevant` `aria-roledescription`
Name From:	author
Accessible Name Required:	False

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

Example 7

<p>...in Order to form a more perfect
<span aria-details="revision-123"><del>Onion</del><ins>Union</ins></span>,
establish Justice...</p>
<!-- ...elsewhere in the document... -->
<div id="revision-123" role="annotation-revision">
<time datetime="1787-09-17">September 17, 1787</time>
by G. Morris
</div>

Characteristics:
Characteristic	Value
Superclass Role:	`annotation`
Required Owned Elements:	`deletion` `insertion`
Inherited States and Properties:	`aria-atomic` `aria-busy (state)` `aria-controls` `aria-current (state)` `aria-describedby` `aria-details` `aria-disabled (state)` `aria-dropeffect` `aria-errormessage` `aria-expanded (state)` `aria-flowto` `aria-grabbed (state)` `aria-haspopup` `aria-hidden (state)` `aria-invalid (state)` `aria-keyshortcuts` `aria-label` `aria-labelledby` `aria-live` `aria-owns` `aria-relevant` `aria-roledescription`
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.

Example 8

<p>Everyone is encouraged to bring a
<span aria-details="suggestion-123"><del>side dish</del><ins>beverage</ins></span>
to share.</p>
<!-- ...elsewhere in the document... -->
<div id="suggestion-123" role="annotation-suggestion">
Change of plans! Can you update this, please?
</div>

Characteristics:
Characteristic	Value
Superclass Role:	`annotation`
Required Owned Elements:	`deletion` `insertion`
Inherited States and Properties:	`aria-atomic` `aria-busy (state)` `aria-controls` `aria-current (state)` `aria-describedby` `aria-details` `aria-disabled (state)` `aria-dropeffect` `aria-errormessage` `aria-expanded (state)` `aria-flowto` `aria-grabbed (state)` `aria-haspopup` `aria-hidden (state)` `aria-invalid (state)` `aria-keyshortcuts` `aria-label` `aria-labelledby` `aria-live` `aria-owns` `aria-relevant` `aria-roledescription`
Name From:	author
Accessible Name Required:	False

`doc-endnote` (role)

One of a collection of notes that occur at the end of a work, or a section within it, that provides additional context to a referenced passage of text.

Note

The doc-endnote role is copied from the [DPUB-ARIA] specification.

Authors MUST ensure that elements with role doc-endnote are contained in, or owned, by an element with the role list.

Example 9

<section role="doc-endnotes">
<h2>Notes</h2>
<ol>
  <li id="6baa07af" role="doc-endnote">Additional results of this study can be found at … </li>
  <li id="7b2c0555" role="doc-endnote">…</li>
  …
</ol>
</section>

Example 10

<section role="doc-endnotes">
<h2>Notes</h2>
<section id="ch1-notes">
  <h3>Chapter 1</h3>
  <div role="list">
     <p id="6baa07af" role="doc-endnote">1. Additional results of this study can be found at … </p>
     <div id="7b2c0555" role="doc-endnote">
        <p>2. The primary source of information …</p>
        <p class="note-cont">In the case of secondary studies …</p>
     </div>
     …
  </div>
</section>
</section>

Characteristics:
Characteristic	Value
Superclass Role:	`listitem`
Related Concepts:	EPUB rearnote [EPUB-SSV]
Required Context Role:	`doc-endnotes`
Inherited States and Properties:	`aria-atomic` `aria-busy (state)` `aria-controls` `aria-current (state)` `aria-describedby` `aria-details` `aria-disabled (state)` `aria-dropeffect` `aria-errormessage` `aria-expanded (state)` `aria-flowto` `aria-grabbed (state)` `aria-haspopup` `aria-hidden (state)` `aria-invalid (state)` `aria-keyshortcuts` `aria-label` `aria-labelledby` `aria-level` `aria-live` `aria-owns` `aria-posinset` `aria-relevant` `aria-roledescription` `aria-setsize`
Name From:	author

`doc-footnote` (role)

Ancillary information, such as a citation or commentary, that provides additional context to a referenced passage of text.

Note

The doc-footnote role is copied from the [DPUB-ARIA] specification.

The doc-footnote role is only for representing individual notes that occur within the body of a work. For collections of notes that occur at the end of a section, see doc-endnotes.

Example 11

<aside id="6baa07af" role="doc-footnote">
* Additional results of this study and similar studies can be found at …
</aside>

Characteristics:
Characteristic	Value
Superclass Role:	`section`
Related Concepts:	EPUB footnote [EPUB-SSV]
Inherited States and Properties:	`aria-atomic` `aria-busy (state)` `aria-controls` `aria-current (state)` `aria-describedby` `aria-details` `aria-disabled (state)` `aria-dropeffect` `aria-errormessage` `aria-expanded (state)` `aria-flowto` `aria-grabbed (state)` `aria-haspopup` `aria-hidden (state)` `aria-invalid (state)` `aria-keyshortcuts` `aria-label` `aria-labelledby` `aria-live` `aria-owns` `aria-relevant` `aria-roledescription`
Name From:	author

3.2.2 Referencing endnotes and footnotes

Typically, references to doc-endnote and doc-footnote content is done via an <a> element with a role value of doc-noteref. The result is the creation of a link from the anchor to the note per the [DPUB-AAM-1.0] spec.

However, authors may provide an alternate experience by using ARIA Annotations and avoid the link-based navigation experience.

Issue

@bigbluehat: pretty sure I've got all this wrong...

Rather than...

Example 12

<p> … as studies have shown.<a id="fnref01" role="doc-noteref">[1]</a></p>

Authors can provide a similar experience via ARIA Annotations by expressing the relationship in this way:

Example 13

<p> … as studies have shown.<a id="fnref01" aria-details="ref01">[1]</a></p>
<!-- ...elsewhere in the document... -->
<section role="doc-endnotes">
 <h2>Notes</h2>
 <ol>
    <li id="ref01" role="doc-endnote">Additional results of this study can be found at … </li>
  </ol>
</section>

3.3 Expressing editorial activities

Edititorial activities can be expressed via ARIA Annotations through the use of the role values of annotation-revision and annotation-suggestion. The use of these role values on the annotation body express that the related annotated content contains the revision or suggested edit.

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

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

Each combination of an [HTML] <ins> and a <del> element 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 14: 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 15: 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.

Example 16

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

3.4 Further annotation labeling

This section is non-normative.

Authors may use aria-label to make long or complex annotation bodies more easily findable and dinstinct from each other by providing a simple textual label.

4. Web Annotation Data Model correlations

This section is non-normative.

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 expressing Web Annotations as simple ARIA Annotations.

Below is an example of translating a "commenting" Web Annotation into an in-page ARIA Annotation expression:

Example 17: Describing a relationship to in-page visible content

Web Annotation commenting on a specific text quotation in a page.

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/simple-comment",
  "type": "Annotation",
  "motivation": "commenting",
  "target": {
    "source": "http://example.org/page-being-commented-on",
    "selector": {
      "type": "TextQuoteSelector",
      "prefix": "cats have been deemed ",
      "exact": "uncooperative",
      "suffix": "."
    }
  },
  "body": {
    "type": "TextualBody",
    "value": "Wouldn't it be simpler to list the cooperative cats?",
    "creator": {
      "type": "Person",
      "name": "Ruff Finkledog"
    }
  }
}

The ARIA Annotation expression of that Web Annotation added to that page.

<!-- HTML of http://example.org/page-being-commented-on -->
<p>The following cats have been deemed <mark aria-details="comment-thread-1">uncooperative</mark>.</p>
<!-- ...elsewhere in the document... -->
<div id="comment-thread-1" role="annotation-commentary">
<h1>Comment by Ruff Finkledog</h1>
<p>Wouldn't it be simpler to list the cooperative cats?</p>
</div>

Note

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

Some Web Annotations applied to a source text may result in simple [HTML] markup only without the need of additional ARIA markup.

Example 18: Describing a Web Annotation that does not have a relationship to other content

Example of a "highlighting" Web Annotation.

<p>The word <mark>cat</mark> is highlighted</p>

Example 19: Describing a Web Annotation that is related to external content only

Example of a "identifying" Web Annotation.

<p>A <a href="https://en.wikipedia.org/wiki/Cat">cat</a>
is one of our favorite quirky pets.</p>

4.1 Purpose to Role Mapping Table

This section is non-normative.

The following table shows the preferred mapping between existing Web Annotation Data Model [annotation-model] motivations and purpose values alongside their ARIA Annotation equivalent role values.

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

Additional scenarios without equivalent Web Annotation motivations/purposes.

Web Annotation motivation/purpose	Additional markup on the annotation body	Markup on the annotated content	Description
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 Annotation 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 Annotation Data Model	`role="annotation-presence"`	`aria-details=[id]`
Does not currently exist in Web Annotation Data Model	`role="doc-footnote"` `role="doc-endnote"` `role="doc-biblioentry"`	`aria-details=[id]`	In-page links for footnotes, endnotes, or bibliographical information in a document

ARIA Annotations

W3C Editor's Draft 10 February 2020

No Longer Maintained!

Abstract

Status of This Document

1. Introduction

1.1 Definitions

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

2. Use Cases

2.1 Web Content

2.2 Assistive Technology

3. Annotation Markup

3.1 Basic expression

3.2 Stating a purpose

3.2.1 Roles for annotation purposes

`annotation` (abstract role)

`annotation-attribution` (role)

`annotation-commentary` (role)

`annotation-presence` (role)

`annotation-revision` (role)

`annotation-suggestion` (role)

`doc-endnote` (role)

`doc-footnote` (role)

3.2.2 Referencing endnotes and footnotes

3.3 Expressing editorial activities

3.4 Further annotation labeling

4. Web Annotation Data Model correlations

4.1 Purpose to Role Mapping Table

A. Rejected annotation purposes

B. References

B.1 Informative references

ARIA Annotations

W3C Editor's Draft 10 February 2020

No Longer Maintained!

Abstract

Status of This Document

1. Introduction

1.1 Definitions

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

2. Use Cases

2.1 Web Content

2.2 Assistive Technology

3. Annotation Markup

3.1 Basic expression

3.2 Stating a purpose

3.2.1 Roles for annotation purposes

annotation (abstract role)

annotation-attribution (role)

annotation-commentary (role)

annotation-presence (role)

annotation-revision (role)

annotation-suggestion (role)

doc-endnote (role)

doc-footnote (role)

3.2.2 Referencing endnotes and footnotes

3.3 Expressing editorial activities

3.4 Further annotation labeling

4. Web Annotation Data Model correlations

4.1 Purpose to Role Mapping Table

5. Platform Accessibility mappings

A. Rejected annotation purposes

B. References

B.1 Informative references

`annotation` (abstract role)

`annotation-attribution` (role)

`annotation-commentary` (role)

`annotation-presence` (role)

`annotation-revision` (role)

`annotation-suggestion` (role)

`doc-endnote` (role)

`doc-footnote` (role)