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/.
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. For details, see the change log and the HTML Diff.
Future updates to this specification may incorporate new features.
Publication as a Proposed Recommendation does not imply endorsement by W3C and its Members.
This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
The W3C Membership and other interested parties are invited to review the document and send comments through 21 April 2025. Advisory Committee Representatives should consult their WBS questionnaires. Note that substantive technical comments were expected during the Candidate Recommendation review period that ended 29 July 2023.
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.1RFC-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.2Normative 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.3Roles 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.1General Rules
User agents MUST conform to the Role Mapping General Rules accessibility API computational requirements in [CORE-AAM-1.1].
7.2Role 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.3Group 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.
A.2.1ARIA WG participants at the time of publication
Rahim Abdi (Apple Inc.)
NAVYA AGARWAL (Adobe)
Mario Batušić (Fabasoft)
Benjamin Beaudry (Microsoft Corporation)
Curt Bellew (Oracle Corporation)
Zoë Bijl (W3C Invited Experts)
Aleksandar Cindrikj (Netcetera)
Keith Cirkel (Microsoft Corporation)
Daniel Clark (Microsoft Corporation)
James Craig (Apple Inc.)
Chris Cuellar (Bocoup)
Hidde de Vries (Logius)
Joanmarie Diggs (Igalia)
Howard Edwards (Bocoup)
James Edwards (TPGi)
Mayuri Faldu (Navy Federal Credit Union)
Betsy Fanning (PDF Association)
Steve Faulkner (TetraLogical Services Ltd)
Jane Fulton (Cisco)
Bryan Garaventa (W3C Invited Experts)
Rashmi Garimella (Google LLC)
Matt Garrish (DAISY Consortium)
Doug Geoffray (Microsoft Corporation)
Jaunita George (Navy Federal Credit Union)
Ariella Gilmore (IBM Corporation)
Glen Gordon (TPGi)
Shirisha Gubba (Google LLC)
Jon Gunderson (University of Illinois)
Oliver Habersetzer (SAP SE)
Theo Hale (Microsoft Corporation)
Sunny Hardasani (Adobe)
Matthew Hardy (Adobe)
Peter Heumader (Fabasoft)
Sarah Higley (Microsoft Corporation)
Hans Hillen (TPGi)
Isabel Holdsworth (TPGi)
Stanley Hon (Microsoft Corporation)
Michael Jackson (Microsoft Corporation)
Duff Johnson (PDF Association)
Summer Jones (Thomson Reuters Corp.)
Sanket Joshi (Microsoft Corporation)
William Kilian (TargetStream Technologies)
Matthew King (Meta)
Zachary Kinsey (TargetStream Technologies)
Greta Krafsig (The Washington Post)
Peter Krautzberger (krautzource UG)
Nina Krauß (SAP SE)
JaEun Jemma Ku (University of Illinois)
Joe Lamyman (TetraLogical Services Ltd)
Charles LaPierre (Benetech)
Philip Lazarevic (Level Access)
Aaron Leventhal (Google LLC)
Brett Lewis (TPGi)
Andy Luhrs (Microsoft Corporation)
Sazzad Mahamud (Google LLC)
Alison Maher (Microsoft Corporation)
Mark McCarthy (University of Illinois)
Clay Miller (Microsoft Corporation)
Daniel Montalvo (W3C)
James Nurthen (Adobe)
Scott O'Hara (Microsoft Corporation)
Lola Odelola (W3C Invited Experts)
Adam Page (Hilton)
Michael Pennisi (Bocoup)
Roberto Perez (Microsoft Corporation)
Giacomo Petri (UsableNet)
Noah Praskins (TPGi)
Daniel Pöll (Fabasoft)
Paul Rayius (Allyant)
Adrian Roselli (W3C Invited Experts)
Marco Sabidussi (UsableNet)
Trisha Salas (Level Access)
Stefan Schnabel (SAP SE)
Harris Schneiderman (Deque Systems, Inc.)
Raymond Schwartz (Navy Federal Credit Union)
Cynthia Shelly (Google LLC)
Tzviya Siegman (W3C)
Arturo Silva (The Washington Post)
Avneesh Singh (DAISY Consortium)
Michael[tm] Smith (sideshowbarker) (W3C)
Francis Storr (Intel Corporation)
Melanie Sumner (W3C Invited Experts)
Alexander Surkov (Igalia)
James Teh (Mozilla Foundation)
Jocelyn Tran (Google LLC)
Léonie Watson (TetraLogical Services Ltd)
Jan Williams (TPGi)
Valerie Young (Igalia)
Kate Zhao (Thomson Reuters Corp.)
Xiao (Helen) Zhou (University of Illinois)
Filippo Zorzi (UsableNet)
A.2.2Enabling 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.