Intro

Microsoft has put forth an excellent proposal for semantic annotations in ARIA. The Microsoft proposal supports code editors as a use case, and supports the following types of annotations: comment, footnote, endnote, spelling error, code error, warning, breakpoint, reference and free-form (localized annotation type).

Another proposal is to leverage the W3C’s Web Annotation Data Model.  However, this seems to contain a lot more structure than is needed for the currently described use cases for in-page annotations, and does not fit in well with ARIA. It brings with it a lot of structure, JSON parsing and external annotation links. As there seem to be supporters of using this spec in the ARIA WG, a discussion will be necessary.

Microsoft Proposal Summary

Microsoft proposed 3 new ARIA attributes (quoted from MS proposal):

• aria-annotationtype: a localized name of the annotation type that applies to the marked up region. A developer should put this around any element(s) that is being annotated. The value should be a human readable name that might get read out by the screen reader - such as "Comment" or "Footnote"
• aria-annotatedby: A space delimited list of element IDs of regions which hold the annotation text that applies to the marked up region. This tag works similar to describedby - a developer can use this to point to the DOM element where the annotation resides.
• aria-annotationfor: A space delimited list of element IDs of regions for which this. This tag is the opposite of aria-annotatedby; rather than pointing to the annotation, this marked up region is the annotation. is placed on the annotation, and points back to the originating text.

Feedback on Current Proposal

Overall the proposal is solid and doable. We may choose to use a proposal that differs very little from this original.

Here is some specific feedback.

• aria-annotationtype:  a localized string is not ideal for Braille display support. Screen readers supporting Braille displays may wish to create abbreviations for various annotation types, such as *ct for comment. Therefore, the annotation type should be semantic. This does not require a new attribute but could also be achieve via new role values on the target annotation element, for example <div role=”comments” id=”comment-thread1>...</div>. For custom annotation types not spec’d, the author can use aria-roledescription on the target element.
• aria-annotatedby: this may be the way to go, but it will require implementation in existing browsers and ATs, which already support a number of relations. It makes sense to take a look and see if any of these relations could be used for annotations.
• aria-annotationfor^[a]: this is redundant with aria-annotatedby and should be removed. The browser implementations automatically compute reverse relations and expose these to assistive technologies.

The proposal also lists a couple of use cases which are already possible with existing ARIA markup. Specifically, spelling and grammar errors are supported by adding aria-invalid=”spelling” or aria-invalid=”grammar” on the range of text.

Basis for Easy ARIA Property Implementation

This is food for thought. It is intended to test the waters for supporting the annotation use cases put forth by Microsoft with minimal code added, and the case of Firefox with IA2/ATK, no new code added.

One issue with new ARIA markup is always implementation. It can take many years to get new markup supported in accessibility APIs, browsers and assistive technologies.

Adding a new relation is the worst part -- it requires a binary update to APIs.

However, two types of markup are very easy to implement:

• New roles: these are easy to support, because even if roles are new, will still be supported in many existing browsers without any code changes. This is because roles can be stacked with more specific roles describing the same object. Browsers that follow CORE-AAM will expose the first known role. For example, <div role=”comment-thread complementary”> will expose the “complementary” role if “comment-thread” is not currently known. In addition, many browsers export the entire role string to screen readers. Screen readers such as JAWS prefer to read the role string directly when it is available.
• New ARIA string attributes: automatic support in Firefox. In the interests of allowing experimentation, Firefox automatically exposes any unknown aria-foo property as an object attribute with a string value. This does not work well for relations, however, where the value as a string is not useful. However, a new aria-annotationtype attribute would automatically be exposed by Firefox as “annotation-type:foo” in IA2 and ATK.

Note that new ARIA relations are not as easy to support as these others. It requires changes to binary APIs, and additional standardization efforts outside of W3C.

Overall, it makes sense to look at leverage existing markup and code, unless it becomes hacky or is against the original intent of the markup.

Specific Recommendations

1. The relationship of content to visible annotations is set via aria-details. If the annotation is hidden, then aria-describedby should be used.
   
2. Annotation type goes on target annotation via the role attribute, and new roles are added to support annotation types needed, such as role=“comment-section”. It is ok to create new role names as long as there is a fallback, e.g. role=”comment-section complementary” and role=”comment group”. We may decide to use a prefix to indicate they are experimental, e.g. “x-comment”, “goog-comment” or “ms-comment”. If the author needs a new type of annotation that hasn’t been spec’d, they can use a localized aria-roledescription.
   
3. Simple spelling and grammar errors can utilize existing the ARIA recommendation of aria-invalid=”spelling” | “grammar”

Benefits of Alternate Proposal

• The only implementation code required in browsers is for new roles.
  In the meantime, ATs on Windows generally read the role attribute directly, and authors can provide a fallback role, so browser implementations do not need to hold things back.
• Light approval process for new roles
• Utilize existing markup
• Less code and markup bloat
• ATs and editing engines can begin work right away