Accessibility/Awesome Fetch API

Awesome Fetch API

Summary

A bulk data fetching API is designed to

• to search the data through a web page
• to retrieve portions of a web page in a single call

which allows to

• decrease number of calls the AT has to poke into a server
• create buffer-less screen readers
• create lazy and lightweight server implementations

A typical scenarios are

• Navigation: AT fetches next/prev heading while the user moves through a web page
• Read a range: AT reads a paragraph by lines

Terms and concepts

Terms:

• Search filters which allows to narrow the data that AT is interested in, for example, find all accessible having a heading role
• Result specifiers which allows to specify what kind of data should be fetched, for example, AT is interested to retrieve accessible names and boundaries
• AOM points (accessible object model aka DOM) which are used to identify and compare ranges in a document. Inspired by DOM point concept.

Also it operates with AT concepts, which are:

• role - a primary characteristic of object like button
• states - boolean characteristics of object like focused or selected
• attributes - a named property having a scalar value (not boolean), for example level:1
• relations - a named property pointing to other object such as label_for
• boundaries - an object boundary in form of a rect
• text - text

Proposal

Search

Search filters

Filter is a boolean expression consisting of conditions combined by boolean operators like: cond1 && cond2 || cond3, where condN is a boolean function which returns true for each accessible object complying a function's criteria.

Suggested boolean functions:

• is(trait) - returns true if an accessible object has a given trait which may be role or state. For example is(listitem) && is(selected) indicates all selected list items.

• has(property[, value]) - return true for an accessible object having a property of a value if provided, for example, has(level, 5) stands for all objects having level attribute with value of 5.

A value of has method is not necessary a scalar value. If a property points to an object, then a boolean function can be used as a value. For example, has(controls, is(listbox)) will return an object which controls a listbox object.

Search/Query API

Search/query is a way to find points or a range complying a search criteria.

query(AOMPoint anchor, String direction, String searchTerm, AOMPoint start, AOMPoint end)

to return a a first AOM point complying a search term.

queryAll(AOMPoint anchor, String direction, String searchTerm, AOMPoint start, AOMPoint end)

to return a list of all entries complying a search term.

Data fetching

Result specifiers

Results specifiers are used to scope fetched data. The format is property:value,[value,...]. For example role;states;attributes:level,xml-roles will return role, states, level and xml-roles attribute.

Data format

The fetching data is supposed to be in JSON format. For example,

[{
  role: "heading",
  states: [
    "invisible", "offscreen"
  ],
  attributes: {
    xml-roles: [ "super-button", "lower-button" ]
  },
  boundaries: [ x, y, width, height ],
  text: [
  ]
},
{
  role: "heading",
  states: [
    "visible", "onscreen"
  ],
  attributes: {
    level: 1
  },
  boundaries: [ x, y, width, height ]
}]

API

So used to fetch all

fetch(in AOMPoint start, in AOMPoint end, out String serializedRange)

returns a string of data of the above format.