Personal tools

Accessibility/JSON ARIA

From MozillaWiki

Jump to: navigation, search


Role extensibility

This is a proposal for how authors could define new ARIA widgets.

Problem statement

The basic problem is that every accessibility API today has a predefined set of roles and properties. Historically, because developers are always creating new things, they end up forcing the new semantics into the existing semantics in inappropriate ways, just to get the behavior they want in one or two ATs they test with. This degrades the accessibility API over time as other ATs end up writing special case code for the various semantics on a per-application basis.

For example, an application may make their software work alright with JAWS, by putting additional status information into aria-describedby. However, this will not work well with changes to the status if the widget is later used dynamically, and will not work with alternative input technology.

Another issue is that standards bodies are slow, and that proprietary vendors do not want to spend the resources to painfully push their new ideas through the standards. In addition, it can be a problem to share IP in the new widgets before the release of a new product.

Use cases

No one wants useless bloat, so the plan is to let ARIA 1.0 settle in and prove that it's necessary and usable via prototyping.

Here are some areas we will be developing use cases for:

  • Vendor-specific widgets
  • New innovations
  • Areas that are too detailed and specific for standardization, but useful for accessibility (such as buddylists or scheduling widgets)
  • Diagrams, where the visual appearance (color, dashed lines, whatever) often indicates properties

How does it work?

A new reusable role is defined by an author or organization via JSON.

The definition includes the following information:

  1. What other role can it be treated as (inheritance)?
  2. What properties does it have, and what is the type of each property
  3. The localization strings necessary to present the object as text
  4. How to treat property changes
  5. Which properties can be set by the user

Status of the discussion

This is a rough proposal for what the community may decide is not necessary, and even if we do it, we'll be waiting until after ARIA 1.0.

  • There is still skepticism of whether this is necessary
  • There are proponents of it among the vendor and accessibiltiy communities
  • The idea has been run by the leads on Firefox accessibility, as well as the Orca and NVDA screen reader projects, and they believe it is feasible

We will be looking to get as many use cases that we can -- specifically we'll need widgets that ARIA 1.0 does not cover which this technology would help define.

Authoring new roles

Pointing to new roles definitions from within document content


  <link rel="ARIA" href=""/>
  <link rel="ARIA" ""/>
  <!-- Optional: pull l10n into separate files -->
  <link rel="ARIA-l10n" href=""/>
  <link rel="ARIA-l10n" href=""/>


XUL and SVG don't define the <link> tag, an open question is how the roles can be included in such documents.

  • One suggestion is to create a new processing instruction like: <?xml-aria href="chrome://calendar/content/access/roles.json" type="text/json"?>
  • Also, since XUL has XBL, and this is effectively a new widget, we could require that it be a new element. The nsIAccessibleProvider interface used in XBL could be extended to provide a property that points to the JSON file. Or, in XBL we could actually directly define the properties that would have been in the JSON.
    • Fallen: processing instruction has the advantage that its a more general form of inclusion, which could possibly lead to allowing aria extensions for any type of XML document. Aaron: I think we might want to allow either. If XBL is available though I suggest to put it there as part of widget definition.
    • Fallen: In XBL, we could probably use the <resources> block to add something, i.e:
<binding id="foobar">
    <stylesheet src="chrome://calendar/skin/foosheet.css"/>
    <aria-roles src="chrome://calendar/content/access/roles.json/>
    <aria-roles src="chrome://calendar/locale/access/roles-l10n.json" l10n="true"/>

Authoring content with the new widget

<div role="buddylist listbox secondary">
  <div role="buddy option" aria-away="true" aria-idle="3 hours, 22 minutes" aria-where="mobile" aria-friends="somefriend"/>

The author only needs to include the fallback role that we inherit from (in this case listbox or option) if they need support for browser version that support ARIA but don't support role extensibility. Browsers that support role extensibility should utilize the "inherits" field from the JSON file.

If you care about validation, you need to write a DTD or schema that handles the new properties.

Defining the widget

Example: buddy widget The definition is in a JSON file, which is easy for any modern browser to parse into an object.

    <!-- Role and property definition -->
    "role": "buddy",
    "inherits": "listbox",
    <!-- can the accessible name be computed from the content -->
    <!-- subtree (e.g. no for a container like a tree, usually yes -->
    <!-- for a focusable widget) -->
    "nameOkFromContents": true,
    "activeProperties": [
      <!-- AT should notify user of changes if the object has focus, -->
      <!-- or on an object controlled by the focus (aria-controls) or --> 
      <!-- if the change occurs inside an ARIA live region (aria-live) -->
      <!-- prop attribute name, data type, optional l10n string -->
      [ "away", "boolean" ],
      [ "activity", "string", "What is this user doing?" ],
      <!-- Treat as an active property in terms of presentation, but -->
      <!-- also allow the user to change the property if it is not marked -->
      <!-- disabled or readonly -->
      <!-- The web page should capture mutation events so that alternative -->
      <!-- input ATs can set the property via the a11y APIs -->
      [ "ignored", "boolean" ],

    "passiveProperties": [    <!--  AT should not notify user of changes, but should still present these properties when the object receives focus -->
      <!-- prop attribute name, data type, optional l10n string -->
      [ "idle",    "string" ],      <!-- readable string -->
      [ "where",   [ "pc", "mobile", "blackberry"] ],    <!-- 3 legal programmatic tokens -->
      [ "friends", "IDREF" ],   <!-- custom relation -->
    <!-- Localization info: can be split into a separate file -->
    "localizedRole": "Buddy",
    "localizedProperties": [
      <!-- Do these need to specified for attributes with boolean or token values? -->
      "friends", "Friends with"
    "localizedValues": [
      <!-- localization for values (booleans and tokens) -->
      <!-- String values are already localized by their nature -->
      <!-- IDREF/IDREFS (relations) should be localized -->
      [ "ignored", [[ "true",       "User blocked" ],
                    [ "false",      "" ],
      [ "away",    [[ "true",       "Currently away"],
                    [ "false",      "Available" ]],
      [ "where",   [[ "pc",         "At desk" ],
                    [ "mobile",     "On phone"],
                    [ "blackberry", "On blackberry" ]]

End user experience

Screen reader users

Screen reader users would be able to hear the role of the new type of object, and associated properties.

Property changes:

  • If the object is focused, then any properties in the activeProperties or liveProperties would be spoken
  • If the object is not focused, then any properties in the liveProperties would be treated as a polite change

Alternative input

If a property is listed under editableProperties, then it is the author's responsibility to handle mutation events and change the state of the widget based on changes to the ARIA attribute.

An alternative input device (an on screen keyboard, voice input software or even a cell phone browser) may choose to provide alternative methods for data entry that are more suitable for that environment. The web page must watch DOMAttrModified (onpropertychange in IE) and map that to the widget state.

How to process

There are 3 ways an AT can handle a new role:

  1. Basic accessibility: just fall back on the role it inherits from -- this is not wrong, but does not offer large improvements
  2. Good accessibility: use the provided JSON semantics for the role and its properties. It describes what to present when the object receives focus, and what to present when an attribute changes.
  3. Enhanced accessibility: via special application code for new role
    • User or vendor-defined AT scripts that operate on a per-webpage or per-role basis
    • If role becomes commonly used across the web, new versions of the core AT can deliver built-in support

Accessibility API Support (ATK/AT-SPI and IAccessible2)

Need to fill this out -- we can either:

  1. use object attributes and events to indicate changed attributes, or
  2. develop new interfaces to expose the custom role information

Using a11y API events may be an issue, in terms of specifying which property has changed. We need either event data or a listener/callback mechanism. Need to think about this.