WAI-ARIA 1.0 User Agent Implementation Guide

1.1. Accessibility APIs

Accessibility APIs covered by this document are:

• ATK/AT-SPI on Linux
• MSAA/IAccessible2 on Windows

Information on how to best expose ARIA to the Mac OS X Accessibility Protocol, UI Automation, or other accessibility APIs is not yet available, but would be appreciated, as would any other feedback on the information contained in this document. If you need to expose to other accessibility APIs, it is recommended closely with assistive technology developers.

1.2. Accessible tree vs. DOM tree - what's the relation?

The accessible tree and the DOM tree are parallel structures. Roughly speaking the accessible tree is a subset of the DOM tree. Accessible objects are created in the accessible tree for every DOM element that should be exposed to an assistive technology, either because it may fire an accessible event or because it has a property, relationship or feature which needs to be exposed. Generally if something can be trimmed out it will be, for reasons of performance and simplicity. For example, a <span> with just a style change and no semantics will not get its own accessible object, but the style change will be exposed through a "text attribute run" in the AccessibleText interface.

In addition to the normal accessible tree, ARIA requires that the elements also be exposed if they have one of the following properties:

• Is focusable, or has an ID attribute and an ancestor with the aria-activedescendant attribute. In either case it may become focused and need to fire a focus event.
• Uses a role attribute but does not contain the role "presentation" before any other mappable role (see role mapping below in Role). If the "presentation" role is used the element should still be exposed if it is focusable, so that focus events can be fired (focus must never be lost).
• Uses one of the global states and properties (but do not use aria-hidden in this list, since hidden elements are typically removed from the accessible object hierarchy anyway)
• Has an ID which is pointed to by another element via an ARIA relation (aria-controls, aria-describedby, aria-flowto, aria-labelledby or aria-owns)

Objects that should be removed from the accessible hierarchy (including their descendants):

• Elements with role="presentation" before any other mappable role, and the element is not focusable
• Table cells where the ancestor <table> has role="presentation", and the table cell is not focusable
• Objects with a role characteristic "Children Presentational: True". This includes the following roles:

When descendant trimming occurs, the Accessible Hypertext interface should also not be exposed for the root object that remains. The descendants are removed because their presence confuses some assistive technologies that do not expect descendants for these roles (e.g. the JAWS virtual buffer would speak the accessible name twice or reveal the slider thumb as an image).

2.1. Controlling focus with tabindex

User agents that support ARIA expand the usage of tabindex, focus, and blur to allow them on all HTML elements. The HTML 5 Working Draft adopts this practice, so this usage is expected to be per specification in the next version of HTML.

In HTML 4 and earlier, only links and form controls participated in the tab order and could receive focus. It was not possible to set focus to other elements, even using script focus methods. While it was possible to include such elements in the tab order with tabindex, it was not possible to make them focusable but not in the tab order. To work around this problem, user agents expand the scope and allowed values of the tabindex attribute.

Essentially, any element such as a div, span or img can be added to the default tab order by setting tabindex="0". In addition, any item with tabindex="-1" can be focused via script or a mouse click, but isn't part of the default tab order.

The tabindex system provides one way to develop custom widgets which are keyboard accessible, from simple widgets like a slider to container widgets like a menubar, tree view or spreadsheet. This system works in older versions of Internet Explorer, as far back as IE 5.5.

The user agent implementation must to do the following to enable tabindex on all elements:

1. Every element can be a) not focusable (nor tabbable), b) focusable but not tabbable, or c) both focusable and tabbable. The presence and value of the tabindex attribute must affect this, even on traditionally non-focusable elements. Mouse click handling and tab navigation code in the user agent must utilize this information.
2. Every HTMLElement must expose the element.tabIndex property.
3. The focus and blur methods should be added to the HTMLElement interface (available to script for every type of element).
4. Any element that can receive focus must fire focus and blur events.
5. The default style sheet must include rules so that any element with :focus receives a focus outline.
6. Canceling a keydown event must also cancel the keypress event, for purposes of compatibility with other browsers. This is necessary because authors supporting Internet Explorer must use keydown events to process keystrokes, where keydown but not keypress events are fired for non-alphanumeric keys. As web page authors implement script control over the keyboard they need to be able to use keydown but cancel the effect of consumed keystrokes such as arrow keys.
7. Ensure that all elements which are focusable are exposed in the accessible object hierarchy, so that when they get focused there is an object to fire an accessibility event for.
8. Expose the FOCUSED and FOCUSABLE accessibility API states, and focus accessibility API event for any element in the accessibility hierarchy, where appropriate.
9. In some cases, Enter on a focused element should act like a click ([HTML5], Section 3.4.1.7).

The HTML 5 spec documents what the extended behavior of tabindex should be ([HTML5], Section 6.5.1). The Gecko documentation on what the behavior should be is in Key-navigable custom DHTML widgets. The documentation for IE's tabindex behavior is in MSDN: tabindex Property. Opera has some simple testcases.

2.2. Controlling focus with ARIA

The aria-activedescendant property could also be used to enable keyboard accessibility on any type of ARIA element. It is often a more convenient way of creating container widget keyboard navigation (where the entire widget is in the tab order just once, but the user can use keystrokes to navigate to descendant items of the container).

Typical usage is described as follows: the author will use tabindex="0" on the container element and aria-activedescendant to point to the ID of the currently active descendant. The author, not the user agent, is responsible for styling the currently active descendant to show it has keyboard focus (not via :focus since actual focus is on the container).

The user agent must do the following to implement aria-activedescendant:

1. Implement the tabindex recommendations from HTML 5 Tabindex. Support for tabindex="0" on all elements is still necessary for authors to use aria-activedescendant system, because the container widget must be in the tab order.
2. For an element that has focus in the DOM, but also has aria-activedescendant which points to a valid ID, do not mark it as focused in the accessibility API (iow don't use the states FOCUSED or FOCUSABLE)
3. When the aria-activedescendant attribute changes on an element that currently has DOM focus, fire an accessibility API FOCUS event on the new active descendant. If aria-activedescendant is cleared or doesn't point to an element in the current document, then fire a focus event for the container object that had the attribute change.
4. For any element with an ID attribute, where the element is a descendant of an element with the aria-activedescendant attribute, apply the following states to the target to ensure the object is accessible:
   1. FOCUSABLE, if the element also has an ARIA role—because the aria-activedescendant of the container can potentially point to it. It is not absolutely necessary to check this when there is no role, because real HTML elements that would be focused would already be focusable.
   2. ACTIVE, whenever the container element sets aria-activedescendant to match the ID of this descendant
   3. FOCUSED, if ACTIVE and the container widget with aria-activedescendant has true DOM focus
5. If the AT sets focus to a descendant of a container with aria-activedescendant, the implementation should change the value of aria-activedescendant to point to that item.

Note for authors: as you move focus to the next descendant, ensure that it is scrolled into view using scrollIntoView()([HTML5], Section 6.4).

2.3. Handling focus changes from the AT

Alternative input software needs to be able to set focus to items exposed as FOCUSABLE. Screen readers, voice input software and on screen keyboards may set focus based on user commands implemented in that software. An MSAA-based AT does this via accSelect(SELFLAG_TAKEFOCUS) and in ATK this comes via AtkComponent::grab_focus.

• If the current element can take real DOM focus, set the DOM focus to it.
• Otherwise, if the current element has an ID and an ancestor with the aria-activedescendant attribute present, then set DOM focus to that ancestor. If successful, then set aria-activedescendant on the ancestor to the ID of the desired element.

Note for authors: you will need an onfocus handler to enable alternative input. For example, when implementing a listbox with focusable list items, don't assume that a mouse click or key press are the only ways a new list item may receive focus. Therefore, any direct style changes to the focused element should happen in the onfocus handler instead of the click and keypress handlers. For the same reason, when using aria-activedescendant, watch for DOMAttrModifed (onpropertychange in IE) to react to changes to these attributes.

3.1. General rules for exposing ARIA semantics

Where possible, ARIA semantics should be exposed through the standard mechanisms of the desktop accessibility API. For example, for ARIA widgets, compare how the widget is exposed in a similar desktop widget. In general most ARIA widget capabilities are exposed through the role, value, Boolean states and relations of the accessibility API.

User agents should notify assistive technology of state changes. Conversely, assistive technology notification of property changes depends on the method by which an assistive technology communicates with the user agent. For example, the aria-multiline property is not something that changes frequently, whereas the aria-checked state changes frequently in response to user input.

3.2. Conflicts between native markup semantics and ARIA

For the core accessibility API properties of role, name, states, value, etc. there is typically only one of each of them. If there is a conflict, ARIA always wins, because ARIA is essentially an override. In other words, if the native markup says there a link, but the ARIA markup says it is a button, then it should be exposed as a button.

3.3. Exposing attributes that don’t directly map to accessibility API properties

When ARIA roles, states and properties don't directly map to an accessibility API, provide a mechanism to expose the raw ARIA data as a text string. User agents may always expose raw ARIA information through this API regardless of whether there is a direct mapping to an accessibility API.

ARIA also exposes new capabilities that desktop accessibility APIs do not currently cover. ARIA uses object attributes to expose semantics not traditionally found in accessibility APIs. Object attributes are name-value pairs that are loosely specified, and very flexible for exposing things that an accessibility API does not have a specific interface for. For example, the aria-live attribute must be exposed via an object attribute because accessibility APIs have no such property available. Specific rules for exposing object attribute name-value pairs are described throughout this document, and rules for the general cases not covered are in States and Object Properties.

For accessibility APIs that do not have "object attributes" per se, it is useful to find a similar mechanism or develop a new interface to expose name/value pairs. Under the Mac OS X Accessibility Protocol, all getters are already simply name-value pairs and it is possible to expose new semantics whenever necessary. Keep in mind, this also requires working with the assistive technology developers to gain support for the new semantics.

3.4. Role mapping

In ARIA, the role attribute may indicate more than one role. The role value is an ordered set of space-separated tokens where each token must be a valid role token. ARIA includes some roles, such as landmarks and advanced widgets, that are not traditionally part of accessibility APIs. In addition, future versions of ARIA may allow for author-defined roles to be used in the role string. In that case, it is expected that a fallback role may be provided after the custom role, in the role string.

Platform accessibility APIs traditionally have had a finite set of predefined roles that are expected by assistive technologies on that platform. There may not always be a perfect match for an ARIA role to a role in the platform accessibility API.

Another difference is that in platform accessibility APIs, only one or two roles may be exposed through the traditional role mechanisms. In contrast, ARIA allows multiple roles to be exposed. Additional roles may be fallback roles. This may be a backup in case a custom role is unknown to some implementations, or it may be a landmark role. Because landmarks do not generally have mappings in platform accessibility APIs, they may occur anywhere within the role string without affecting how the first widget role is exposed.

The user agent should expose roles so that the standard role mechanism of the accessibility API provides the best-fit widget role, yet the entire role string is also available for parsing:

1. The first role token with a known mapping to accessibility APIs should be used when mapping to the accessibility API via the standard role mechanism of the accessibility API. Use the role table below and apply any special case rules that are specified.
2. Roles defined in the ARIA spec as "abstract" should not be mapped via the standard role mechanism of the accessibility API. The abstract roles are:
3. If no mapping to a standard role in the platform accessibility API is found, the algorithm used to map to a platform accessibility API role should act as if no role attribute is present. In other words, the UA will fall back on normal processing of the base markup for the element with the role attribute. For example, for <table role="log"> use the tag name "table" to determine what platform accessibility API role to use. For <input type="text" role="search">, use the platform accessibility API for a text input.
4. The entire role string should be exposed in the object attribute "xml-roles". This allows assistive technologies to do their own additional processing of roles.

Dynamic role changes are considered an error in the WAI-ARIA specification, and are discussed in Error Handling.

• Under MSAA/IAccessible2, the events are EVENT_OBJECT_HIDE and EVENT_OBJECT_SHOW, with EVENT_OBJECT_REORDER on the parent accessible object
• Under ATK/AT-SPI, fire children-changed:remove followed by children-changed:add for the new object

3.5. State and Property Mapping

This section describes how to expose additional states and object properties not covered in previous sections of this document. Where possible, API standard states are used. When that is not possible, object attributes (or a similar mechanism) is required.

1. Compute the managed states such as VISIBLE/INVISIBLE, SHOWING/OFFSCREEN, etc. This typically is done in the same way as for ordinary elements that do not have ARIA attributes present. For FOCUSABLE/FOCUSED, it may be affected by aria-activedescendant—see the rules in aria-activedescendant.
2. Add in states and object attributes supported by the accessibility implementation for the base markup.
3. Apply special case rules for the primary role: some roles require additional states to be exposed. For the primary mapped role, look in the role table in Role for additional states and object attributes to expose.
4. Compute states for the relevant ARIA properties. To determine the relevant ARIA properties, combine the list of the global states and properties with the specific states and properties supported by the roles on the current element. For example, all elements support aria-required, but only some roles such as role="checkbox" support the aria-checked property. To compute the properties see the table below.
5. For forward compatibility with new ARIA properties in future versions, expose all properties not in this table with an object attribute, removing the "aria-" prefix from the name. For example, aria-foo="bar" would be exposed with an object attribute foo=bar, since aria-foo is not a currently known ARIA property from the spec (it is not already covered by a more specific mapping rule).

ARIA property mapping rule table:

Important Note: any ARIA property of type Boolean or NMTOKEN is undefined if the ARIA attribute is not present, or is set to the zero-length string or "undefined". This does not affect properties of type string, decimal, IDREF or IDREFS.

Also, ensure that states and properties which are not global are only computed on elements with roles that support them.

For dynamic ARIA property changes, expose an event such as a state change event to indicate the change occurred. For simplicity and performance the user agent may trim out change events for properties that assistive technologies typically ignore changes in. However, at a minimum, state change events should be fired for changes in:

• aria-disabled: this will affect ENABLED and SENSITIVE states
• aria-checked or aria-pressed: this will affect the CHECKED state. A state change for MIXED/INDETERMINATE should also be fired when the value changes to or from "mixed".
• aria-invalid: this will affect the INVALID_ENTRY state (be careful, the INVALID state in APIs means no valid state, which is different)
• aria-expanded, aria-readonly, aria-required: these will affect the states of similar names in the accessibility APIs

Other types of changes:

• aria-activedescendant changes affect focus events as described in aria-activedescendant
• aria-valuenow changes affect value change events as described in Value
• role or aria-multiselectable changes should cause the destruction and recreation of a new accessible object for the element, because it is a major change where the interfaces exposed via accessibility APIs change as well.
• aria-selected changes should affect selection events as described in Selection

3.6. Special Processing Requiring Additional Computation

4.1. Exposing Supplemental Interfaces

In general the base markup should determine what interfaces are exposed for an accessible object. However, in the following cases ARIA markup changes which interfaces should be exposed:

• AccessibleValue: as discussed in Value, the value interface should be exposed for objects with an aria-valuenow property when one of the roles on the elements supports that. Because the Value interface allows values to be set, aria-valuenow is really read/write. The browser needs to set aria-valuenow if the value is changed to a valid value, and the current element is not readonly or disabled. Note to authors: anything that implements valuenow needs to watch for on DOMAttrChanged (onpropertychange in IE) and react to it.
• AccessibleTable: should be exposed for role="grid" and role="treegrid" (XXX note: not done in Mozilla—known bug)
• AccessibleSelection: should be exposed when a role supports aria-multiselectable, and aria-multiselectable="true"
• AccessibleHypertext: this should not be exposed if the elements descendants have been trimmed off based on the role. See 11.3.2.1 for which roles have their subtrees trimmed.

Although it is not an ARIA-specific issue, for the purposes of accessible web applications it is worth mentioning some additionally useful rules for exposing interfaces:

• AccessibleAction: should at least be exposed for anything with a "click" handler, although future versions of ARIA may bring more precision to the handling of actions. Also need to support doDefaultAction in MSAA (same as action #0)—this maps to a click.
• AccessibleEditabletext: should be exposed for any region made editable via contenteditable or designMode

4.2. Actions

Actions are exposed by the following rules

• element has registered 'click' event handler
• element is xlink
• element has ARIA role allowing action (see the following table)

4.3. Changes to document content or node visibility

Processing document changes is important regardless of ARIA. We document how to do it here, however, because it is so crucial to enable the AJAX and other use cases that often go along with ARIA markup.

Fire these events for text changes:

1. When text is removed, fire IA2_EVENT_TEXT_REMOVED (IA2) and text_changed:delete (ATK)
2. When text is inserted, IA2_EVENT_TEXT_INSERTED (IA2) and text_changed:insert (ATK)
3. When text is changed, fire a removal event followed by an insertion event

Fire these events for node changes where the node in question is an element and has an accessible object:

1. When a subtree is removed or hidden, fire EVENT_OBJECT_HIDE (MSAA) and children_changed:remove (ATK). The MSAA event called EVENT_OBJECT_DESTROY is not used because this has a history of stability issues and ATs avoid it. In any case, from the user's point of view, there is no difference between something that is hidden or destroyed.
2. When a subtree is inserted or shown, fire EVENT_OBJECT_SHOW (MSAA) and children_changed:add (ATK).
3. When a subtree is moved, treat it as a removal from one place and insertion in another
4. When a subtree is changed (e.g. replaceNode) treat it as a removal and insertion

For node changes where the node is not an element or has no accessible object:

• This will likely affect the text output by the AccessibleText interface. Compute and fire relevant text change events as described above.
• There may be accessible descendants. The appropriate show/hide/children_changed events must be fired for the first-line descendants with accessible objects.

When firing any of the above-mentioned change events, it is very useful to provide information about whether the change was caused by user input (as opposed to a timeout initiated from the page load, etc.). This allows the AT to have different rules for presenting changes from the real world as opposed to from user action. Mouse hovers are not considered explicit user input because they can occur from accidental bumps of the mouse.

To expose whether a change occurred from user input:

• In ATK this can be provided by appending the string ":system" to the event name when the user did not cause the change.
• In MSAA, which screen readers typically access in process on the same thread, the best practice is to expose the object attribute "event-from-user-input=true" on the accessible object for the event, if the user caused the change.

Exposing additional useful information about the context of the change:

• The member-of relation on the accessible event object should point to any ancestor with aria-atomic="true" (if any).
• The container-live, container-channel, container-relevant, container-busy, container-atomic object attributes should be exposed on the accessible event object, providing the computed value for the related ARIA properties. The computed value is the value of the closest ancestor. It is recommended to not expose the object attribute if the default value is used.

Additional MSAA events may be necessary:

• If something changes in an ancestor with a mapped MSAA role of ROLE_SYSTEM_ALERT, then an EVENT_SYSTEM_ALERT event should be fired for the alert. The alert role has an implied value of "assertive" for the aria-live property.
• Menu events may need to be fired. See Menus in MSAA/IAccessible2.

4.4. Selection

There are two cases for selection:

• Single selection
• Multiple selection

In the single selection case, it is not always necessary to manage selection events and states separate from focus, since selection mirrors focus. One exception is for tab lists. In the case of a tab, if either the tab or its associated tabpanel has focus, then the tab is considered to be SELECTED. To implement this: the user agent can walk up the parent chain from the focus until it finds the a tabpanel, then traverse the aria-labelledby relation from the tabpanel to the related tab, and mark the found tab as focused.

The multiple selection case occurs when aria-multiselectable="true" on an element with a role that supports that property. There are several important aspects:

1. Expose the correct states on the container: MULTISELECTABLE and, in MSAA, it is also EXTSELECTABLE
2. Support the AccessibleSelection interface on the container with aria-multiselectable. The selection interface can be used by an AT to actually set the selection on a descendant. This should fail for the specified descendant if aria-selected is undefined, which indicates the element is not SELECTABLE. It should also fail if the specified descendant is DISABLED or READONLY for any reason. When clearing selection on an item, set aria-selected="false" but do not remove the attribute, so that it is still SELECTABLE. Note to authors: scripts need to watch for mutations to aria-selected, since selection may be caused by an AT and not the mouse or keyboard.
3. Fire the correct events when aria-selected changes on a descendant, as follows:

4.5. Menus in MSAA/IAccessible2

Under MSAA special events are required whenever a menu is opened or closed. These events must be nested and symmetrical:

• A single EVENT_SYSTEM_MENUSTART when a menu in a menubar is opened. This is triggered when focus goes to a menuitem and menu mode is not currently active, but it must be fired before any EVENT_SYSTEM_MENUPOPUPSTART events. The menubar must be either in the natural parent chain or or in the one caused by aria-owns (use RELATION_NODE_CHILD_OF impl to go to aria-owns ancestor).
• One or more EVENT_SYSTEM_MENUPOPUPSTART when a menu popup is made visible. This is triggered when a menu is made visible, but should only be fired once until the menu is closed and reopened again. Care should be taken to check descendants for role="menu" when any subtree is made visible. The menu role might not be on the root node of the change.
• A focus event on a menuitem. This must occur after the EVENT_SYSTEM_MENUPOPUPSTART.
• One or more EVENT_SYSTEM_MENUPOPUPEND when a menu popup is hidden. This should only be fired for an accessible menu object when an EVENT_SYSTEM_MENUPOPUPSTART was fired for it, and it should only be fired once in that case. Care should be taken to check descendants for role="menu" when a subtree is hidden.
• A final EVENT_SYSTEM_MENUEND when in menubar mode (a MENUSTART was fired) and either all menus in a menubar are closed or focus goes somewhere other than a menuitem (such as a control in a dialog).

Because screen readers on Windows will typically ignore focus events while menus are opened, it is important to fire the symmetrical EVENT_SYSTEM_MENUPOPUPEND followed by a EVENT_SYSTEM_MENUEND when something other than a menu received focus (e.g. selecting the menu option opened a dialog). In fact, screen readers can become quite confused if the correct ending menu events are not fired.

That said, perfectly symmetrical events are difficult to achieve. Because menus can be made visible hidden using a variety of techniques, it is advisable that an implementation keep track of the menu events fired and ensure symmetrization.

5.1. Documents, Handling frame and iframe elements

• Root ARIA node: the <body> or <frameset> in HTML, or the document element in all other languages.
• Sub-document: any document created from a <frame>, <iframe> or similar mechanism. A sub-document may contain a document, an application or any widget such as a calendar pulled in from another server. In the accessibility hierarchy there are two accessible objects for this situation—one represents the <frame>/<iframe> element in the parent document, which parents a single accessible object child representing the spawned document contents.
• Outer document accessible: the accessible object representing the <frame>/<iframe>
• Inner document accessible: the accessible object representing the root ARIA node for the spawned document. It is a child of the outer document accessible.

Computing the accessible name for an outer document accessible:

• Accessibility properties for the outer document accessible are exposed as they normally are for an element.

Computing the accessible name for an inner document accessible:

1. If a sub-document, do a depth-first name computation using aria-labelledby from the <frame> or <iframe>. If the name is still empty, use the title attribute from the <frame> or <iframe>.
2. If the name is still empty, use a depth-first name computation from aria-labelledby on the document's root ARIA node. If it is still empty use the title attribute on the root ARIA node.
3. If the name is still empty, and the <title> element or some other means exists of getting the accessible name, use that.

Computing the accessible description for an inner document accessible:

1. If a sub-document, do a depth-first description computation using aria-describedby from the <frame> or <iframe>.
2. If the description is still empty, use a depth-first name computation from aria-describedby on the document's root ARIA node.

Computing container-foo on any node in a sub document: For container-live, container-atomic, container-relevant, container-channel and container-busy, inner nodes override outer nodes from within the same documment, because the inner subtree is the more relevant context. However, outer documents override inner documents, because the outer document author may be different and may wish to define the context for a live iframe. Therefore:

1. Walk the entire parent chain including that from outer documents, collecting the properties from aria-live, aria-atomic, aria-relevant, and aria-busy into the container-[property] object attribute
2. If a node sets a given object attribute, set a state that doesn't allow that value to change that object attribute again within the document
3. When entering a parent document, refresh the state to again allow override of each of these object properties

Computing other properties for an inner document accessible:

1. For user-controlled properties (aria-selected, aria-valuenow, aria-valuetext, aria-activedescendant), use the ARIA markup on the root ARIA node only
2. The ARIA properties on the outer document accessible take precedence, on a property-by-property basis
3. If the outer document accessible does not set a property, the root ARIA node for the inner document is used
4. Relations are not concatenative. If the outer document accessible sets a relation, that is used instead of anything set on the inner document's root ARIA node.

5.2. CSS Selectors

Support for attribute selectors must include ARIA attributes. For example, .fooMenuItem['aria-haspop=true'] should select all elements with class "fooMenuItem", and ARIA attribute "aria-haspopup" with value true.  The presentation must be updated for dynamic changes to ARIA attributes. This allows authors to match styling with ARIA semantics.

6.1. Definitions

• Target Element: An element specified in an ARIA relation. For example, in aria-controls=”elem1”, “elem1” is the target element.
• Valid ID: A specified ID for an ARIA property that satisfies the following condition:
  It refers to a target element that exists in the same document as the element specifying the relation.

6.2. Value type: IDREF and IDREFS

Q: What happens if an invalid ID is specified for an ARIA property?
A: The UA will ignore the ID.

Q: What if the ARIA property contains a mixture of valid and invalid IDs?
A: The UA will return only the objects corresponding to the valid IDs.

Q: What if there is more than one element with the same ID?
A: The first element found with the given ID will be what is used. The behavior will be the same as getElementById, and it is the web author’s responsibility to ensure uniqueness of IDs.

Q: What if the same element is specified multiple times in a single ARIA relation of type IDREFS?
A: [Might need to reword this, I am assuming the return is an array of pointers to accessible objects] The UA will return multiple pointers to the same object.

Q: What happens if more than one ID is specified (space-separated list) for a property that is a single IDREF?
A: The UA will use the whole string (without splitting on spaces) and try to look up an element that has that ID. For instance aria-activedescendant="foo bar" would match id="foo bar".

[IE-specific] Q: What if the author is using the “name” attribute instead of “id”, since they were interchangeable in IE7?
A: IE will only match on the “id” attribute, regardless of the version of the document. We believe that matching only on the “id” attribute is the correct behavior.

6.3. Value type: decimal

Q: What if a non-numeric value is specified for a decimal type?
A: If asking for the string version of the property, the UA will simply return the string specified by the author. However, if a decimal is specifically requested, the UA will fail to convert the string to a decimal and return a default value.

6.4. UA Validation

In general, UAs do not do much validation of ARIA properties. Some minor validation may occur on request, such as making sure valid IDs are specified for ARIA relations, and enforcing things like aria-posinset being within 1 and aria-setsize, inclusive. UAs are not responsible for logical validation, such as the following:

1. Circular references created by relations, such as specifying that two elements own each other.
2. Correct usage with regard to DOM tree structure, such as an aria-activedescendant being a DOM-descendant of the element with the relation.
3. Elements with ARIA roles correctly implement the specified role. For example, UAs do not verify that an element with role=”checkbox” actually behaves like a checkbox.

6.5. Roles

Q. What happens if the author uses an abstract role, or a role that does not map to a standard role for the platform accessibility API?
A: This is defined in the spec:

http://www.w3.org/TR/2009/WD-wai-aria-20090224/#ua_role_identify If a given role in the role attribute is abstract or has no mapping, skip that role. If no known role is found in the role attirbute, the UA will just act as if the role attribute was absent except it would still expose the role attribute's value in the xml-roles object attribute.

Q. What happens if the author changes the role of an element dynamically?
A. This is considered incorrect practice by the ARIA specification, can cause changes in what accessible interfaces need to be supported by an object, and is unexpected by ATs. Therefore, the least expensive way to handle dynamic role changes is used: fire the appropriate invalidation events for object with the role change, so that the AT will update its cache or virtual buffer. The relevant invalidation events are:

• Under MSAA/IAccessible2, the events are EVENT_OBJECT_HIDE and EVENT_OBJECT_SHOW, with EVENT_OBJECT_REORDER on the parent accessible object
• Under ATK/AT-SPI, fire children-changed:remove followed by children-changed:add for the new object

6.6. States and Properties 

Q. Some ARIA properties are not global, and are only supported on certain roles. What should be mapped when a dependent ARIA property is used where it is not supported?
A. The user agent should act as if the ARIA property is absent, and not not map the given ARIA property through the platform accessibility API. For example, aria-checked should not be exposed as CHECKED on <div role="grid">

Q. What should be exposed to platform accesibility APIs when an ARIA property contains an unknown or disallowed value?
A.1 When exposing as an object attribute, expose the unknown value—do not vet it against possible values.
A.2 When exposing as a platform API Boolean state, treat "", "undefined" or no attribute present as false. Treat any other value as true.
A.3 Otherwise, ignore the value and treat the property as not present

Q. What should be exposed to platform accessibility APIs when an unknown ARIA property is used?
A. Expose an object attribute with the same name, with the "aria-" prefix removed. The object attribute's value should be equal to the ARIA property's value. This will help with forward compatibility with new ARIA properties in future versions.

Q. What if aria-hidden does not match the reality of whether a node is visible or not?
A. This error condition does not even need to be checked for, because aria-hidden is not necessary when a layout API provides more complete information. Advisory: it is incorrect use of ARIA if an element with aria-hidden="true" is visible. The aria-hidden property is exposed only so that DOM-based assistive technologies can be informed of visibility changes. Since layout APIs will be able to provide the most complete set of all truly hidden nodes, they should be used instead of the aria-hidden attribute.  

Q. If an AT uses a platform accessibility API setter to change aria-valuenow, should the user agent ensure that the new value is within the bounds set by aria-valuemin and aria-valuemax?
A. Yes. Do not set the value if it is out of bounds. Note, however, that it is still the final responsibility of the web application to ensure the validity of user data.

Q. If an AT uses a platform accessibility API getter to get aria-valuenow, should the user agent ensure that it is within the bounds set by aria-valuemin and aria-valuemax?
A. No, simply expose the aria-valuenow whether it is out of bounds or not.

Q. What if an element has the aria-valuetext property set, but not aria-valuenow?
A. Expose the valuetext as defined in this guide, but return an error for any value getter that only returns a numeric type

Q. If an AT uses a platform accessibility API setter to change aria-valuenow, should the user agent ensure that the current element is not disabled or readonly?
A. Yes. Do not set the value if the current element is disabled or readonly

Q. If an AT uses the platform accessibility API to change whether an element is selected, should the user agent ensure that the element is not disabled?
A. Yes. Do not set or clear the selection if the current element is disabled (although it is okay to change the selection for readonly elements)

Q. Should the user agent check whether aria-activedescendant actually points to a descendant or not?
A. No

Q. What if aria-level, aria-setsize or aria-posinset are 0 or negative?
A. Return 1

Q. What if aria-posinset is larger than aria-setsize?
A. Return aria-setsize in place of aria-posinset

Q. What if a required aria property (i.e. required for a given role) is missing for a given widget?
A.

6.7. Propagating errors to ATs

Most errors that occur due to ARIA are not propagated to callers. For example, finding an invalid ID in a list of IDREFS is not a reason to return an error code to the caller. Errors that can propagate are specific to certain ARIA properties.

1. ChildID and aria-owns: aria-owns appends a list of children to an element. Specifying a child ID outside of the new valid range still returns an error, the same that would occur before when specifying an invalid child ID.

7.1. References

This section is informative.

[ARIA]

Accessible Rich Internet Applications (WAI-ARIA) Version 1.0. L. Seeman, M. Cooper, R. Schwerdtfeger, L. Pappas, Editors, W3C Working Draft (work in progress), 4 February 2008. This version of WAI-ARIA is available at http://www.w3.org/TR/2008/WD-wai-aria-20080204/. Latest version of WAI-ARIA available at http://www.w3.org/TR/wai-aria/.

[HTML5]

HTML 5, D. Hyatt, I. Hickson, Editors, W3C Working Draft (work in progress), 22 January 2008, http://www.w3.org/TR/2008/WD-html5-20080122/. Latest version of HTML 5 available at http://www.w3.org/TR/html5/.

7.2. Acknowledgments

This section is informative.

The following people contributed to the development of this document.