ARIA annotations draft proposal

Annotation use cases and markup

What is an annotation?

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

High level use cases

• Document editor
• Code editor
• Published content

Proposed Markup

• 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 type of annotation. 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 types)
  • 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.

Roles for annotations

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 not annotation type is specified.
• 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 types 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.

Rejected aria-annotation values

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

Platform Accessibility mappings

• 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