This is a supplementary document to Accessibility API specification. It introduces accessible taxonomies, the hierarchies of accessible properties like roles and states, and interconnections between them. The assistive technology can extract information about taxonomies used in the document. The web author can extend existing taxonomies to express semantics of the content if he needs to.

This is a work in progress.

Things we want feedback on!

Taxonomy API

The API provides bunch of interfaces that are used to obtain the information about accessible taxonomies and to extend the existing ones.

Terms

An accessible taxonomy or taxonomy of an accessible property like role or state is a hierarchy of all possible values of the accessible property. The taxonomy describes each value by set of attributes, for example, it may provide a human readable localized string for the property value. Also the taxonomy describes interconnection between values from other taxonomies, for example, link role may be connected to visited state.

Understanding the terms.

Each accessible element is described by accessible properties like role, state, actions etc. Every accessible property may take a range of values, for example, checkbox and paragraph as values for role. All accessible properties may have various dependencies, for example, checked state can be applied to checkbox role, however it's not applicable to paragraph role. Accessible property values and their dependencies are structured into taxonomies. The assistive technology can operate with them.

The values of accessible properties and their relations are specific to a markup whose semantics they serve to express. If the web author needs to expose the semantics of some new kind, for example, to describe a music sheet, then he may need to introduce new roles, states etc and describe them. To do so the web author needs to extend existing taxonomies. The assistive technology will able then to understand the semantics of the content and figure out a connection between 'known' taxa. For example, if the web author introduces checklistitem role which is compound from two checkbox and listitem roles, i.e it inherits properties of both of them then the web author should integrate the new role into existing role hierarchy.

Extension to the AccessibleDocument interface

An accessible document provides a method to import taxonomies. 

partial interface AccessibleDocument {
  Taxon? taxonOf(DOMString taxonomy, DOMString name);
  void import(TaxaLibrary library);
};

taxonOf method

Returns a taxon object of Taxon interface for the given taxonomy and taxon name. Depending on the taxonomy the object may implement other interfaces derived from Taxon interface. For example, the returned object for the role taxonomy implements RoleTaxon interface.

The example logs out the whole role taxonomy. 

function logRoleTree(taxon, level) {
  for (let i = 0; i < taxon.children.length; i++) {
    var child = taxon.children[i];
    console.log(`{$level} ${child.name}`);
    logRoleTree(child, `${level}.${i}`);
  }
}
let taxon = document.a11ement.taxonOf('role', 'base');
logRoleTree(taxon);

import method

Imports taxonomies from the given library into the document taxonomies.

In the example bunch of ARIA DPUB roles are imported into document's taxonomy. 

var DPUBRoles = {
  appendix: {
    description: "appendix",
    parents: "section",
    attributes: {
      landmark: "appendix"
    }
  },
  bibliography: {
    description: "bibliography",
    parents: "list",
    attributes: {
      landmark: "bibliography"
    }
    owns: "biblioentry"
  },
  biblioentry: {
    description: "reference",
    parents: "listitem"
  }
};

document.a11ement.import({
  id: 'ARIA:DPUB',
  roles: DPUBRoles
});

The method can be used to extend existing taxonomies. If, for example, the library describes an role that exists in the taxonomy then the role taxon is extended by new properties, if they don't conflict to the existing ones. In latter case an exception is thrown.

In the example the root role taxon is extended by new states and relations. These states and relations will be applicable to all roles in the taxonomy. 

var library = {
  roles: {
    '*': {
      states: [
        'highlightable', 'highlighted'
      ],
      relations: [
        'highlight-comment-for',
        'highlight-commented-by'
      ]
    }
  },
  states: {
    highlightable: { },
    highlighted: {
      description: 'user choice'
    }
  },
  relations: {
    'highlight-comment-for': { },
    'highlight-commented-by': {
      description: 'commented by'
    }
  }
}

TaxaLibrary dictionary

A collection of taxonomies extensions to the document's taxonomies. 

dictionary TaxaLibrary {
  DOMString id;
  TaxaStack roles;
  TaxaStack states;
  TaxaStack attributes;
  TaxaStack actions;
  TaxaStack relations;
};

interface TaxaStack {
  readonly maplike<DOMString, TaxonDict>;
};

id attribute

The id attribute represents the library id, used for identification proposes.

roles attribute

The roles attribute represents a collection of roles injected into the browser's taxonomy by the library. Returned object implements TaxaStack interface, which is a map with role as a key and its description object as a value. The role description object implements RoleTaxonDict dictionary.

states attribute

The states attribute represents a collection of states injected into the browser's taxonomy by the library. Returned object implements TaxaStack interface, which is a map with state as a key and its description object as a value. The description object implements TaxonDict dictionary.

attributes attribute

The attributes attribute represents a collection of attributes injected into the browser's taxonomy by the library. Returned object implements TaxaStack interface, which is a map with attribute as a key and its description object as a value. The description object implements TaxonDict dictionary.

relations attribute

The relations attribute represents a collection of relations injected into the browser's taxonomy by the library. Returned object implements TaxaStack interface, which is a map with relation as a key and its description object as a value. The description object implements TaxonDict dictionary.

TaxonDict interface

An object describing a taxon. 

dictionary TaxonDict {
  DOMString description;
};

dictionary RoleTaxonDict : TaxonDict {
  sequence<DOMString> parents;
  sequence<DOMString> children;

  sequence<DOMString> owns;
  sequence<DOMString> states;
  sequence<DOMString> attributes;
  sequence<DOMString> relations;
  sequence<DOMString> actions;
};

TaxonDict and RoleTaxonDict dictionaries is a replication of corresponding Taxon and RoleTaxon interfaces.

Taxon interface

An object containing a name and description of a taxon. 

interface Taxon {
  stringifier readonly attribute DOMString name;
  readonly attribute DOMString description;
};

RoleTaxon interface

An object describing role taxon. 

[NoInterfaceObject]
interface RoleTaxon : Taxon {
  readonly attribute sequence<RoleTaxon> parents;
  readonly attribute sequence<RoleTaxon> children;

  readonly attribute sequence<RoleTaxon> owns;
  readonly attribute sequence<DOMString> states;
  readonly attribute object attributes;
  readonly attribute object relations;
  reaodnly attribute sequence<Taxon> actions;
};

Example of usage

Example of a script that logs to console all accessible element states. 

let al = document.getElementById("foo").a11ement;
for (let state of al.states) {
  console.log(state);
}

Dependencies

The following definitions are in the [[!Accessible API]] specification:

Acknowledgements

Many thanks to.