Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                

Digital Publishing Accessibility API Mappings 1.1

W3C Working Draft

More details about this document
This version:
https://www.w3.org/TR/2024/WD-dpub-aam-1.1-20240621/
Latest published version:
https://www.w3.org/TR/dpub-aam-1.1/
Latest editor's draft:
https://w3c.github.io/dpub-aam/
History:
https://www.w3.org/standards/history/dpub-aam-1.1/
Commit history
Implementation report:
https://w3c.github.io/test-results/dpub-aam/
Editors:
Matt Garrish (DAISY Consortium)
Tzviya Siegman (Wiley)
Former editors:
(Igalia, S.L.)
(Knowbility)
Feedback:
GitHub w3c/dpub-aam (pull requests, new issue, open issues)
public-aria@w3.org with subject line [dpub-aam-1.1] … message topic … (archives)

Copyright © 2015-2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

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 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. 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 the Recommendation 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 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.

This document is governed by the 03 November 2023 W3C Process Document.

1. Introduction

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 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 agents MUST conform to Supporting Keyboard Navigation requirements in [CORE-AAM-1.1].

4. Mapping WAI-ARIA to accessibility APIs

4.1 General rules for exposing WAI-ARIA semantics

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

5. Conflicts between native markup semantics and WAI-ARIA

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

6. Exposing attributes that do not directly map to accessibility API properties

User agents MUST conform to Exposing attributes that do not directly map to accessibility API properties in [CORE-AAM-1.1].

7. Role mapping

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.

7.2.1 doc-abstract

DPUB-ARIA Specification doc-abstract
Computed Role doc-abstract
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_SECTION
  • Object attribute xml-roles:doc-abstract.
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'abstract'
ATK/AT-SPI Role

Expose ROLE_SECTION and object attribute xml-roles:doc-abstract.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXApplicationGroup
  • AXRoleDescription: 'group'
  • AXCustomContent: { label: "type", value: "abstract" }

7.2.2 doc-acknowledgments

DPUB-ARIA Specification doc-acknowledgments
Computed Role doc-acknowledgments
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_LANDMARK
  • Object attribute xml-roles:doc-acknowledgments.
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'acknowledgements'
  • Landmark Type is Custom
  • Localized Landmark Type is 'acknowledgements'
ATK/AT-SPI Role

Expose ROLE_LANDMARK and object attribute xml-roles:doc-acknowledgments.

Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXLandmarkRegion
  • AXRoleDescription: 'region'
  • AXCustomContent: { label: "type", value: "acknowledgements" }

7.2.3 doc-afterword

DPUB-ARIA Specification doc-afterword
Computed Role doc-afterword
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_LANDMARK
  • Object attribute xml-roles:doc-afterword.
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'afterword'
  • Landmark Type is Custom
  • Localized Landmark Type is 'afterword'
ATK/AT-SPI Role

Expose ROLE_LANDMARK and object attribute xml-roles:doc-afterword.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXLandmarkRegion
  • AXRoleDescription: 'region'
  • AXCustomContent: { label: "type", value: "afterword" }

7.2.4 doc-appendix

DPUB-ARIA Specification doc-appendix
Computed Role doc-appendix
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_LANDMARK
  • Object attribute xml-roles:doc-appendix.
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'appendix'
  • Landmark Type is Custom
  • Localized Landmark Type is 'appendix'
ATK/AT-SPI Role

Expose ROLE_LANDMARK and object attribute xml-roles:doc-appendix.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXLandmarkRegion
  • AXRoleDescription: 'region'
  • AXCustomContent: { label: "type", value: "appendix" }

7.2.6 doc-biblioentry

DPUB-ARIA Specification doc-biblioentry
Computed Role doc-biblioentry
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose

ROLE_SYSTEM_LISTITEM + STATE_SYSTEM_READONLY

IAccessible2:

Object attribute xml-roles:doc-biblioentry.
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'biblioentry'
ATK/AT-SPI Role

Expose ROLE_LIST_ITEM and object attribute xml-roles:doc-bilioentry.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: <nil>
  • AXRoleDescription: 'group'
  • AXCustomContent: {}

7.2.7 doc-bibliography

DPUB-ARIA Specification doc-bibliography
Computed Role doc-bibliography
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_LANDMARK
  • Object attribute xml-roles:doc-bibliography.
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'bibliography'
  • Landmark Type is Custom
  • Localized Landmark Type is 'biblography'
ATK/AT-SPI Role

Expose ROLE_LANDMARK and object attribute xml-roles:doc-bibliography.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXLandmarkRegion
  • AXRoleDescription: 'region'
  • AXCustomContent: { label: "type", value: "bibliography" }

7.2.8 doc-biblioref

DPUB-ARIA Specification doc-biblioref
Computed Role doc-biblioref
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose
  • ROLE_SYSTEM_LINK + STATE_LINKED
  • STATE_LINKED on all descendants

IAccessible2:

  • Object attribute xml-roles:doc-biblioref.
  • AccessibleHypertext interface
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'biblioref'
ATK/AT-SPI Role

Expose ROLE_LINK and object attribute xml-roles:doc-biblioref.
Mac AX API
  • AXRole: AXLink
  • AXSubrole: <nil>
  • AXRoleDescription: 'link'
  • AXCustomContent: { label: "type", value: "bibliography" }

7.2.9 doc-chapter

DPUB-ARIA Specification doc-chapter
Computed Role doc-chapter
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_LANDMARK
  • Object attribute xml-roles:doc-chapter.
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'chapter'
  • Landmark Type is Custom
  • Localized Landmark Type is 'chapter'
ATK/AT-SPI Role

Expose ROLE_LANDMARK and object attribute xml-roles:chapter.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXLandmarkChapter
  • AXRoleDescription: 'chapter'
  • AXCustomContent: {}

7.2.10 doc-colophon

DPUB-ARIA Specification doc-colophon
Computed Role doc-colophon
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose

IA2_ROLE_SECTION

IAccessible2: Object attribute xml-roles:doc-colophon.
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'colophon'
ATK/AT-SPI Role

Expose ROLE_SECTION and object attribute xml-roles:doc-colophon.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXApplicationGroup
  • AXRoleDescription: 'group'
  • AXCustomContent: { label: "type", value: "colophon" }

7.2.11 doc-conclusion

DPUB-ARIA Specification doc-conclusion
Computed Role doc-conclusion
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_LANDMARK
  • Object attribute xml-roles:doc-conclusion.
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'conclusion'
  • Landmark Type is Custom
  • Localized Landmark Type is 'conclusion'
ATK/AT-SPI Role

Expose ROLE_LANDMARK and object attribute xml-roles:doc-conclusion.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXLandmarkRegion
  • AXRoleDescription: 'region'
  • AXCustomContent: { label: "type", value: "conclusion" }

7.2.12 doc-cover

DPUB-ARIA Specification doc-cover
Computed Role doc-cover
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose

ROLE_SYSTEM_GRAPHIC

IAccessible2: Object attribute xml-roles:doc-cover.
UIA Control Type + Other Features Control Type is Image
ATK/AT-SPI Role

expose ROLE_IMAGE and object attribute xml-roles:doc-cover.
Mac AX API
  • AXRole: AXImage
  • AXSubrole: <nil>
  • AXRoleDescription: 'cover image'
  • AXCustomContent: {}

7.2.13 doc-credit

DPUB-ARIA Specification doc-credit
Computed Role doc-credit
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose

IA2_ROLE_SECTION

IAccessible2:

Object attribute xml-roles:doc-credit
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'credit'
ATK/AT-SPI Role

Expose ROLE_SECTION and object attribute xml-roles:doc-credit.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXApplicationGroup
  • AXRoleDescription: 'group'
  • AXCustomContent: {}

7.2.14 doc-credits

DPUB-ARIA Specification doc-credits
Computed Role doc-credits
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_LANDMARK
  • Object attribute xml-roles:doc-credits.
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'credits'
  • Landmark Type is Custom
  • Localized Landmark Type is 'credits'
ATK/AT-SPI Role

Expose ROLE_LANDMARK and object attribute xml-roles:doc-credits.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXLandmarkRegion
  • AXRoleDescription: 'region'
  • AXCustomContent: { label: "type", value: "credits" }

7.2.15 doc-dedication

DPUB-ARIA Specification doc-dedication
Computed Role doc-dedication
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose

IA2_ROLE_SECTION

IAccessible2:

Object attribute xml-roles:doc-dedication
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'dedication'
ATK/AT-SPI Role

Expose ROLE_SECTION and object attribute xml-roles:doc-dedication.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXApplicationGroup
  • AXRoleDescription: 'group'
  • AXCustomContent: { label: "type", value: "dedication" }

7.2.16 doc-endnote

DPUB-ARIA Specification doc-endnote
Computed Role doc-endnote
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose

ROLE_SYSTEM_LISTITEM + STATE_SYSTEM_READONLY

IAccessible2:

Object attribute xml-roles:doc-endnote.
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'endnote'
ATK/AT-SPI Role

Expose ROLE_LIST_ITEM and object attribute xml-roles:doc-endnote.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: <nil>
  • AXRoleDescription: 'group'
  • AXCustomContent: {}

7.2.17 doc-endnotes

DPUB-ARIA Specification doc-endnotes
Computed Role doc-endnotes
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_LANDMARK
  • Object attribute xml-roles:doc-endnotes.
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'endnotes'
  • Landmark Type is Custom
  • Localized Landmark Type is 'endnotes'
ATK/AT-SPI Role

Expose ROLE_LANDMARK and object attribute xml-roles:doc-endnotes.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXLandmarkRegion
  • AXRoleDescription: 'region'
  • AXCustomContent: { label: "type", value: "end notes" }

7.2.18 doc-epigraph

DPUB-ARIA Specification doc-epigraph
Computed Role doc-epigraph
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose

IA2_ROLE_SECTION

IAccessible2:

Object attribute xml-roles:doc-epigraph
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'epigraph'
ATK/AT-SPI Role

Expose ROLE_SECTION and object attribute xml-roles:doc-epigraph.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXApplicationGroup
  • AXRoleDescription: 'group'
  • AXCustomContent: { label: "type", value: "epigraph" }

7.2.19 doc-epilogue

DPUB-ARIA Specification doc-epilogue
Computed Role doc-epilogue
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_LANDMARK
  • Object attribute xml-roles:doc-epilogue.
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'epilogue'
  • Landmark Type is Custom
  • Localized Landmark Type is 'epilogue'
ATK/AT-SPI Role

Expose ROLE_LANDMARK and object attribute xml-roles:doc-epilogue.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXLandmarkRegion
  • AXRoleDescription: 'region'
  • AXCustomContent: { label: "type", value: "epilog" }

7.2.20 doc-errata

DPUB-ARIA Specification doc-errata
Computed Role doc-errata
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_LANDMARK
  • Object attribute xml-roles:doc-errata
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'errata'
  • Landmark Type is Custom
  • Localized Landmark Type is 'errata'
ATK/AT-SPI Role

Expose ROLE_LANDMARK and object attribute xml-roles:doc-errata.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXLandmarkRegion
  • AXRoleDescription: 'region'
  • AXCustomContent: { label: "type", value: "errata" }

7.2.21 doc-example

DPUB-ARIA Specification doc-example
Computed Role doc-example
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose

IA2_ROLE_SECTION

IAccessible2:

Object attribute xml-roles:doc-example
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'example'
ATK/AT-SPI Role

Expose ROLE_SECTION and object attribute xml-roles:doc-example.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXApplicationGroup
  • AXRoleDescription: 'group'
  • AXCustomContent: { label: "type", value: "example" }

7.2.22 doc-footnote

DPUB-ARIA Specification doc-footnote
Computed Role doc-footnote
MSAA + IAccessible2 Role + Other IAccessible2 Features

Expose IAccessible2:

  • IA2_ROLE_FOOTNOTE
  • Object attribute: xml-roles:doc-footnote
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'footnote'
ATK/AT-SPI Role

Expose ROLE_FOOTNOTE and object attribute xml-roles:doc-footnote.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXApplicationGroup
  • AXRoleDescription: 'group'
  • AXCustomContent: { label: "type", value: "footnote" }

7.2.23 doc-foreword

DPUB-ARIA Specification doc-foreword
Computed Role doc-foreword
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_LANDMARK
  • Object attribute xml-roles:doc-foreword
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'foreword'
  • Landmark Type is Custom
  • Localized Landmark Type is 'foreword'
ATK/AT-SPI Role

Expose ROLE_LANDMARK and object attribute xml-roles:doc-foreword.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXLandmarkRegion
  • AXRoleDescription: 'region'
  • AXCustomContent: { label: "type", value: "foreword" }

7.2.24 doc-glossary

DPUB-ARIA Specification doc-glossary
Computed Role doc-glossary
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_LANDMARK
  • Object attribute xml-roles:doc-glossary
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'glossary'
  • Landmark Type is Custom
  • Localized Landmark Type is 'glossary'
ATK/AT-SPI Role

Expose ROLE_LANDMARK and object attribute xml-roles:doc-glossary.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXLandmarkRegion
  • AXRoleDescription: 'region'
  • AXCustomContent: { label: "type", value: "glossary" }

7.2.25 doc-glossref

DPUB-ARIA Specification doc-glossref
Computed Role doc-glossref
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose
  • ROLE_SYSTEM_LINK + STATE_LINKED
  • STATE_LINKED on all descendants

IAccessible2:

  • Object attribute xml-roles:doc-glossref.
  • AccessibleHypertext interface
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'glossref'
ATK/AT-SPI Role

Expose ROLE_LINK and object attribute xml-roles:doc-glossref.
Mac AX API
  • AXRole: AXLink
  • AXSubrole: <nil>
  • AXRoleDescription: 'link'
  • AXCustomContent: { label: "type", value: "glossary" }

7.2.26 doc-index

DPUB-ARIA Specification doc-index
Computed Role doc-index
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_LANDMARK
  • Object attribute xml-roles:doc-index
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'index'
  • Landmark Type is Custom
  • Localized Landmark Type is 'index'
ATK/AT-SPI Role

Expose ROLE_LANDMARK and object attribute xml-roles:doc-index.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXLandmarkNavigation
  • AXRoleDescription: 'navigation'
  • AXCustomContent: { label: "type", value: "index" }

7.2.27 doc-introduction

DPUB-ARIA Specification doc-introduction
Computed Role doc-introduction
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_LANDMARK
  • Object attribute xml-roles:doc-introduction
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'introduction'
  • Landmark Type is Custom
  • Localized Landmark Type is 'introduction'
ATK/AT-SPI Role

Expose ROLE_LANDMARK and object attribute xml-roles:doc-introduction.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXLandmarkRegion
  • AXRoleDescription: 'region'
  • AXCustomContent: { label: "type", value: "introduction" }

7.2.28 doc-noteref

DPUB-ARIA Specification doc-noteref
Computed Role doc-noteref
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose
  • ROLE_SYSTEM_LINK + STATE_LINKED
  • STATE_LINKED on all descendants

IAccessible2:

  • Object attribute xml-roles:doc-noteref.
  • AccessibleHypertext interface
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'noteref'
ATK/AT-SPI Role

Expose ROLE_LINK and object attribute xml-roles:doc-noteref.
Mac AX API
  • AXRole: AXLink
  • AXSubrole: <nil>
  • AXRoleDescription: 'link'
  • AXCustomContent: { label: "type", value: "note" }

7.2.29 doc-notice

DPUB-ARIA Specification doc-notice
Computed Role doc-notice
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose

IA2_ROLE_NOTE

IAccessible2:

Object attribute xml-roles:doc-notice.
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'notice'
ATK/AT-SPI Role

Expose ROLE_COMMENT and object attribute xml-roles:doc-notice.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXDocumentNote
  • AXRoleDescription: 'note'
  • AXCustomContent: {}

7.2.30 doc-pagebreak

DPUB-ARIA Specification doc-pagebreak
Computed Role doc-pagebreak
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose

ROLE_SYSTEM_SEPARATOR

IAccessible2:

Object attribute xml-roles:doc-pagebreak.
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'pagebreak'
ATK/AT-SPI Role

Expose ROLE_SEPARATOR and object attribute xml-roles:doc-pagebreak.
Mac AX API
  • AXRole: AXSplitter
  • AXSubrole: <nil>
  • AXRoleDescription: 'splitter'
  • AXCustomContent: { label: "type", value: "page break" }

7.2.32 doc-pageheader

DPUB-ARIA Specification doc-pageheader
Computed Role doc-pageheader
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_HEADER
  • Object attribute xml-roles:doc-pageheader
UIA Control Type + Other Features
  • Control Type is Text
  • Control Pattern: Annotation
  • Annotation.AnnotationTypeId: Header
ATK/AT-SPI Role Expose

ROLE_HEADER and object attribute xml-roles:doc-pageheader.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: <nil>
  • AXRoleDescription: 'group'
  • AXCustomContent: { label: "type", value: "header" }

7.2.33 doc-pagelist

DPUB-ARIA Specification doc-pagelist
Computed Role doc-pagelist
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_LANDMARK
  • Object attribute xml-roles:doc-pagelist
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'pagelist'
  • Landmark Type is Custom
  • Localized Landmark Type is 'pagelist'
ATK/AT-SPI Role Expose

ROLE_LANDMARK and object attribute xml-roles:doc-pagelist.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXLandmarkNavigation
  • AXRoleDescription: 'navigation'
  • AXCustomContent: { label: "type", value: "page list" }

7.2.34 doc-part

DPUB-ARIA Specification doc-part
Computed Role doc-part
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_LANDMARK
  • Object attribute xml-roles:doc-part
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'part'
  • Landmark Type is Custom
  • Localized Landmark Type is 'part'
ATK/AT-SPI Role

Expose ROLE_LANDMARK and object attribute xml-roles:doc-part.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXLandmarkRegion
  • AXRoleDescription: 'region'
  • AXCustomContent: { label: "type", value: "part" }

7.2.35 doc-preface

DPUB-ARIA Specification doc-preface
Computed Role doc-preface
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_LANDMARKi
  • Object attribute xml-roles:doc-preface
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'preface'
  • Landmark Type is Custom
  • Localized Landmark Type is 'preface'
ATK/AT-SPI Role

Expose ROLE_LANDMARK and object attribute xml-roles:doc-preface.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXLandmarkRegion
  • AXRoleDescription: 'region'
  • AXCustomContent: { label: "type", value: "preface" }

7.2.36 doc-prologue

DPUB-ARIA Specification doc-prologue
Computed Role doc-prologue
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_LANDMARK
  • Object attribute xml-roles:doc-prologue
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'prologue'
  • Landmark Type is Custom
  • Localized Landmark Type is 'prologue'
ATK/AT-SPI Role

Expose ROLE_LANDMARK and object attribute xml-roles:doc-prologue.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXLandmarkRegion
  • AXRoleDescription: 'region'
  • AXCustomContent: { label: "type", value: "prolog" }

7.2.37 doc-pullquote

DPUB-ARIA Specification doc-pullquote
Computed Role doc-pullquote
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_SECTION
  • Object attribute xml-roles:doc-pullquote
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'pullquote'
ATK/AT-SPI Role

Expose ROLE_SECTION and object attribute xml-roles:doc-pullquote.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXApplicationGroup
  • AXRoleDescription: 'group'
  • AXCustomContent: { label: "type", value: "pull quote" }

7.2.38 doc-qna

DPUB-ARIA Specification doc-qna
Computed Role doc-qna
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose

IA2_ROLE_SECTION

IAccessible2:

Object attribute xml-roles:doc-qna
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'qna'
ATK/AT-SPI Role

Expose ROLE_SECTION and object attribute xml-roles:doc-qna.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXApplicationGroup
  • AXRoleDescription: 'group'
  • AXCustomContent: { label: "type", value: "Q&A" }

7.2.39 doc-subtitle

DPUB-ARIA Specification doc-subtitle
Computed Role doc-subtitle
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose IAccessible2:
  • IA2_ROLE_HEADING
  • Object attribute xml-roles:doc-subtitle
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'subtitle'
ATK/AT-SPI Role

Expose ROLE_HEADING and object attribute xml-roles:doc-subtitle.
Mac AX API
  • AXRole: AXHeading
  • AXSubrole: AXSubtitle
  • AXRoleDescription: 'subtitle'
  • AXCustomContent: {}

7.2.40 doc-tip

DPUB-ARIA Specification doc-tip
Computed Role doc-tip
MSAA + IAccessible2 Role + Other IAccessible2 Features Expose

IA2_ROLE_NOTE

IAccessible2:

Object attribute xml-roles:doc-tip
UIA Control Type + Other Features
  • Control Type is Text
  • Localized Control Type is 'tip'
ATK/AT-SPI Role

Expose ROLE_COMMENT and object attribute xml-roles:doc-tip.
Mac AX API
  • AXRole: AXGroup
  • AXSubrole: AXDocumentNote
  • AXRoleDescription: 'note'
  • AXCustomContent: { label: "type", value: "tip" }

7.2.41 doc-toc

DPUB-ARIA Specification doc-toc
Computed Role doc-toc
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:

9. State and Property Mapping

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

10. Special Processing Requiring Additional Computation

10.1 Name and Description

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

10.2 Relations

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 agents MUST 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. Appendices

A.1 Change Log

A.1.1 Substantive changes since the First Public Working Draft

  • 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.

A.1.2 Other substantive changes since Digital Publishing Accessibility API Mappings 1.0

  • 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.

B. References

B.1 Normative references

[ACCNAME-1.2]
Accessible Name and Description Computation 1.2. Bryan Garaventa; Melanie Sumner. W3C. 21 June 2024. 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. 21 June 2024. W3C Candidate Recommendation. 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. 27 February 2024. W3C Candidate Recommendation. URL: https://www.w3.org/TR/dpub-aria-1.1/
[html]
HTML Standard. Anne van Kesteren; Domenic Denicola; 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

B.2 Informative references

[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. W3C. 28 March 2019. 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/