Digital Publishing Accessibility API Mappings 1.1 (original) (raw)

Abstract

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 platformaccessibility 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 theW3C standards and drafts 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. A list of all substantive changes is available in the change log.

This document was published by the Accessible Rich Internet Applications Working Group as a Working Draft using theRecommendation track.

Publication as a Working Draft 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.

This document was produced by a group operating under theW3C Patent Policy.W3C maintains apublic 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 containsEssential Claim(s) must disclose the information in accordance withsection 6 of the W3C Patent Policy.

This document is governed by the03 November 2023 W3C Process Document.

Table of Contents

1. Abstract
2. Status of This Document
3. 1. Introduction
4. 2. Conformance
   1. 2.1 Normative and Informative Sections
   2. 2.2 Roles deprecated in DPUB-ARIA
5. 3. Supporting keyboard navigation
6. 4. Mapping WAI-ARIA to accessibility APIs
   1. 4.1 General rules for exposing WAI-ARIA semantics
7. 5. Conflicts between native markup semantics and WAI-ARIA
8. 6. Exposing attributes that do not directly map to accessibility API properties
9. 7. Role mapping
   1. 7.1 General Rules
   2. 7.2 Role Mapping Tables
      1. 7.2.1 doc-abstract
      2. 7.2.2 doc-acknowledgments
      3. 7.2.3 doc-afterword
      4. 7.2.4 doc-appendix
      5. 7.2.5 doc-backlink
      6. 7.2.6 doc-biblioentry
      7. 7.2.7 doc-bibliography
      8. 7.2.8 doc-biblioref
      9. 7.2.9 doc-chapter
      10. 7.2.10 doc-colophon
      11. 7.2.11 doc-conclusion
      12. 7.2.12 doc-cover
      13. 7.2.13 doc-credit
      14. 7.2.14 doc-credits
      15. 7.2.15 doc-dedication
      16. 7.2.16 doc-endnote
      17. 7.2.17 doc-endnotes
      18. 7.2.18 doc-epigraph
      19. 7.2.19 doc-epilogue
      20. 7.2.20 doc-errata
      21. 7.2.21 doc-example
      22. 7.2.22 doc-footnote
      23. 7.2.23 doc-foreword
      24. 7.2.24 doc-glossary
      25. 7.2.25 doc-glossref
      26. 7.2.26 doc-index
      27. 7.2.27 doc-introduction
      28. 7.2.28 doc-noteref
      29. 7.2.29 doc-notice
      30. 7.2.30 doc-pagebreak
      31. 7.2.31 doc-pagefooter
      32. 7.2.32 doc-pageheader
      33. 7.2.33 doc-pagelist
      34. 7.2.34 doc-part
      35. 7.2.35 doc-preface
      36. 7.2.36 doc-prologue
      37. 7.2.37 doc-pullquote
      38. 7.2.38 doc-qna
      39. 7.2.39 doc-subtitle
      40. 7.2.40 doc-tip
      41. 7.2.41 doc-toc
10. 8. Translatable Values
11. 9. State and Property Mapping
12. 10. Special Processing Requiring Additional Computation
13. 10.1 Name and Description
14. 10.2 Relations
15. 10.3 Group Position
16. 11. Actions
17. 12. Events
18. 13. Security Considerations
19. 14. Privacy Considerations
20. A. Appendices
21. A.1 Change Log
    1. A.1.1 Substantive changes since the First Public Working Draft
    2. A.1.2 Other substantive changes since Digital Publishing Accessibility API Mappings 1.0
22. A.2 Acknowledgments
    1. A.2.1 ARIA WG participants at the time of publication
    2. A.2.2 Enabling funders
23. B. References
24. B.1 Normative references
25. B.2 Informative references

This section is non-normative.

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 theAccessible 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 theWAI-ARIA Overview.

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 words MUST and SHOULD in this document are to be interpreted as described inBCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

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 can contain examples of recommended practice, but it is not required to follow such recommendations in order to conform to this specification.

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.

Enabling keyboard navigation in web applications is a necessary step toward making accessible web applications possible. Conforming user agents MUST conform toSupporting Keyboard Navigation requirements in [CORE-AAM-1.1].

This section MUST conform to General rules for exposing WAI-ARIA semantics in [CORE-AAM-1.1].

User agents MUST conform to Conflicts between native markup semantics and WAI-ARIA in [CORE-AAM-1.1].

User agents MUST conform toExposing attributes that do not directly map to accessibility API properties 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 are usually 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.

User agents MUST conform to the Role Mapping General Rules accessibility API computational requirements in [CORE-AAM-1.1].

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.

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:

• AXRoleDescription
• the value property of AXCustomContent
• Localized Control Type
• Localized Landmark Type

This section describes how to expose WAI-ARIA states and objectproperties. User agents MUST conform to theState and Property Mapping accessibility API computational requirements in [CORE-AAM-1.1].

When computing an accessible name or accessible description, user agents MUST conform to the section titledText Alternative Computation of the [ACCNAME-1.2] specification.

User agents MUST conform to the Relation accessibility API computational requirements in [CORE-AAM-1.1].

User agents MUST conform to the Group Position accessibility API computational requirements in [CORE-AAM-1.1].

User agents MUST conform to the Actions accessibility API computational requirements in [CORE-AAM-1.1].

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 agents MUST support the [CORE-AAM-1.1]Events mappings.

This section is non-normative.

This specification introduces no new security 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.

• 01-Dec-2023: Removed the mappings that implied doc-biblioentry and doc-endnote on listitem descendants doc-bibliograph and doc-endnotes, respectively.

• 10-Jan-2023: Added section on translatable values.

• 04-Jan-2023: Fixed incorrect doc-pagebreak role mentioned in ATK/AT-SPI mapping for doc-preface.

• 04-Jan-2023: Updated Mac AX API mappings to add AXCustomContent fields.

• 20-Sep-2021: Added mappings for doc-pageheader and doc-pagefooter roles.

This section is non-normative.

The following people contributed to the development of this document:

• Aaron Leventhal
• Bogdan Brinza
• Daniel Montalvo
• Denis Ah-Kang
• James Craig
• James Nurthen
• joanmarie
• Joseph Scheuhammer
• Peter Krautzberger
• Richard Schwerdtfeger
• Valerie Young

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.

[ACCNAME-1.2]

Accessible Name and Description Computation 1.2. Bryan Garaventa; Melanie Sumner. W3C. 24 March 2025. W3C Working Draft. URL: https://www.w3.org/TR/accname-1.2/

[CORE-AAM-1.1]

Core Accessibility API Mappings 1.1. Joanmarie Diggs; Joseph Scheuhammer; Richard Schwerdtfeger; Michael Cooper; Andi Snow-Weaver; Aaron Leventhal. W3C. 14 December 2017. W3C Recommendation. URL: https://www.w3.org/TR/core-aam-1.1/

[core-aam-1.2]

Core Accessibility API Mappings 1.2. Valerie Young; Alexander Surkov. W3C. 24 March 2025. CRD. URL: https://www.w3.org/TR/core-aam-1.2/

[dpub-aria-1.1]

Digital Publishing WAI-ARIA Module 1.1. Matt Garrish; Tzviya Siegman. W3C. 18 March 2025. W3C Proposed Recommendation. URL: https://www.w3.org/TR/dpub-aria-1.1/

[html]

HTML Standard. Anne van Kesteren; Domenic Denicola; Dominic Farolino; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/

[infra]

Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/

[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119

[RFC8174]

Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174

[dom]

DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/

[fingerprinting-guidance]

Mitigating Browser Fingerprinting in Web Specifications. Nick Doty; Tom Ritter. W3C. 21 March 2025. W3C Working Group Note. URL: https://www.w3.org/TR/fingerprinting-guidance/

[wai-aria]

Accessible Rich Internet Applications (WAI-ARIA) 1.0. James Craig; Michael Cooper et al. W3C. 20 March 2014. W3C Recommendation. URL: https://www.w3.org/TR/wai-aria/