The Digital Publishing Accessibility API Mappings (DPub-AAM) defines how user agents map the Digital
Publishing WAI-ARIA Module [dpub-aria-1.1] markup to platform accessibility APIs. It is intended for user agent
developers responsible for accessibility in their user agent so that they can support the accessibility
content produced for digital publishing.
Status of This Document
This section describes the status of this
document at the time of its publication. A list of current W3C
publications and the latest revision of this technical report can be found
in the W3C technical reports index at
https://www.w3.org/TR/.
Feature development for this version is complete. This is a Candidate Recommendation published to obtain feedback before finalization of the specification.
While feedback on any aspect of the specification is encouraged, we would particularly like feedback on the addition of the doc-pageheader and doc-pagefooter roles.
Comments are welcome at any time but most especially before 27 April 2024.
The primary change since the First Public Working Draft was to update the Mac AX API mappings to add the
AXCustomContent fields for announcing roles. Feedback on any aspect of the specification is
encouraged. A list of all substantive changes is available in the change
log.
Publication as a Candidate Recommendation does not
imply endorsement by W3C and its Members. A Candidate Recommendation Snapshot has received
wide review, is intended to
gather
implementation experience,
and has commitments from Working Group members to
royalty-free licensing
for implementations.
This Candidate Recommendation is not expected to advance to Proposed
Recommendation any earlier than 27 April 2024.
This document was produced by a group
operating under the
W3C Patent
Policy.
W3C maintains a
public list of any patent disclosures
made in connection with the deliverables of
the group; that page also includes
instructions for disclosing a patent. An individual who has actual
knowledge of a patent which the individual believes contains
Essential Claim(s)
must disclose the information in accordance with
section 6 of the W3C Patent Policy.
The implementation of this specification in user agents enables authors to produce more accessible
e-books, by conveying structural book constructs used by the digital publishing industry to assistive
technologies. It does this by extending the Core
Accessibility API Mappings 1.1 [CORE-AAM-1.1] and the Accessible Name and Description: Computation
1.2 [ACCNAME-1.2] specifications for user agents. It provides Accessibility API Mapping
guidance for the roles defined in the Digital Publish WAI-ARIA Module.
The DPub-AAM is part of the WAI-ARIA suite
described in the WAI-ARIA Overview.
2. Conformance
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key word MUST in this document
is to be interpreted as described in
BCP 14
[RFC2119] [RFC8174]
when, and only when, they appear in all capitals, as shown here.
2.1 RFC-2119 Keywords
RFC-2119 keywords are formatted in uppercase and contained in a strong element with
class="rfc2119". When the keywords shown above are used, but do not share this
format, they do not convey formal information in the RFC 2119 sense, and are merely explanatory
(i.e., informative). As much as possible, such usages are avoided in this specification.
2.2 Normative and Informative Sections
The indication whether a section is normative or non-normative (informative) applies to the entire
section including sub-sections.
Informative sections provide information useful to understanding the specification. Such sections may
contain examples of recommended practice, but it is not required to follow such recommendations in
order to conform to this specification.
2.3 Roles deprecated in DPUB-ARIA
The DPUB-ARIA specification [dpub-aria-1.1] lists some roles as deprecated. Although this means
authors are encouraged not to use these roles, it is expected that the roles could still be used in
legacy content. Therefore, it is important that user agents continue to map these roles to
accessibility APIs, and doing so is part of conformance to this specification. When future versions
of the DPUB-ARIA specification change such roles from deprecated to removed, they will be removed
from the mappings as well and user agents will no longer be asked to continue support for those
roles.
3. Supporting keyboard navigation
Enabling keyboard navigation in web applications is a necessary step toward making accessible web
applications possible. Conforming user agentsMUST conform to Supporting Keyboard Navigation
requirements in [CORE-AAM-1.1].
Platform accessibility APIs traditionally have had a finite set of predefined roles that
are expected by assistive technologies on that platform and only one or two roles
may be exposed. In contrast, WAI-ARIA allows
multiple roles to be specified as an ordered set of space-separated valid role tokens. The additional
roles are fallback roles similar to the concept of specifying multiple fonts in case the first choice
font type is not supported.
7.1 General Rules
User agents MUST conform to the Role Mapping General Rules accessibility API
computational requirements in [CORE-AAM-1.1].
7.2 Role Mapping Tables
Note
Translators: For label text associated with the following table and its toggle buttons,
see the mappingTableLabels object in the <head> section of this
document.
This section defines how WAI-ARIA digital publishing roles map to platform accessibility APIs.
Elements having roles with a prefix value of doc-, that are not listed in this role
mapping table, have no normative mappings.
MSAA + IAccessible2 Role + Other IAccessible2 Features
Expose IAccessible2:
IA2_ROLE_LANDMARK
Object attribute xml-roles:doc-toc
UIA Control Type + Other
Features
Control Type is Text
Localized Control Type is 'toc'
Landmark Type is Custom
Localized Landmark Type is 'toc'
ATK/AT-SPI
Role
Expose ROLE_LANDMARK and object attribute
xml-roles:doc-toc.
Mac AX API
AXRole: AXGroup
AXSubrole: AXLandmarkNavigation
AXRoleDescription: 'navigation'
AXCustomContent: { label: "type", value: "table of contents"
}
8. Translatable Values
The HTML specification states that other specifications can define translatable attributes [html]. The language and
directionality of each attribute value is the same as the language and
directionality of the element [html].
To be understandable by assistive technology users, the following role mapping values
intended for human consumption should be translated when a page is localized:
User agents MUST conform to the Relation
accessibility API computational requirements in [CORE-AAM-1.1].
10.3 Group Position
User agents MUST conform to the Group Position
accessibility API computational requirements in [CORE-AAM-1.1].
11. Actions
User agents MUST conform to the Actions accessibility API computational requirements in
[CORE-AAM-1.1].
12. Events
user agents fire events for user actions, WAI-ARIA
state changes, changes to document content or node visibility, changes in
selection, and operation of menus. Conforming user agentsMUST support
the [CORE-AAM-1.1] Events
mappings.
13. Security Considerations
This section is non-normative.
This specification introduces no new security considerations.
14. Privacy Considerations
This section is non-normative.
In accordance with Web Platform
Design Principles, this specification provides no programatic interface to determine if
information is being used by assistive technologies. However, this specification does allow an author to
present different information to users of assistive technologies from the information available to users
who do not use assistive technologies. This is possible using many features of the DPUB-ARIA
specification, just as this is possible using many other parts of the web technology stack. This content
disparity could be abused to perform active
fingerprinting of users of assistive technologies.
20-Sep-2021: Added mappings for doc-pageheader and doc-pagefooter roles.
A.2 Acknowledgments
This section is non-normative.
The following people contributed to the development of this document:
James Craig (Apple Inc.)
Romain Deltour (DAISY Consortium)
Joanmarie Diggs (Igalia)
Matt Garrish (DAISY Consortium)
George Kerscher (DAISY Consortium)
Peter Krautzberger (W3C Invited Experts)
Charles Lapierre (Benetech)
Aaron Leventhal (Google)
Daniel Montalvo (W3C Staff)
James Nurthen (Adobe)
Scott O'Hara (Microsoft Corporation)
Gregorio Pellegrino (Fondazione LIA)
Tzviya Siegman (Wiley)
Avneesh Singh (DAISY Consortium)
Valerie Young (Igalia)
A.2.1 Enabling funders
This publication has been funded in part with U.S. Federal funds from the Department of Education, National Institute on Disability, Independent Living, and Rehabilitation Research (NIDILRR), initially under contract number ED-OSE-10-C-0067, then under contract number HHSP23301500054C, and now under HHS75P00120P00168. The content of this publication does not necessarily reflect the views or policies of the U.S. Department of Education, nor does mention of trade names, commercial products, or organizations imply endorsement by the U.S. Government.