The Digital Publishing Accessibility API Mappings (SVG-AAM) defines how user agents map the Digital Publishing WAI-ARIA Module [[!SVG]] markup to platform accessibility application programming interfaces (APIs). It is intended for HTML and SVG language user agent developers responsible for accessibility in their user agent so that they can support the accessibility content produced by the digital publishing.

The implementation of this specification in enables authors to produce more accessible e-books, by conveying structural book constructs used by the digital publishing industry to assistive technologies.

Introduction

This specification indicates whether a section is normative or informative and the classification applies to the entire section. A statement "This section is normative" or "This section is informative" applies to all sub-sections of that section.

Normative sections provide requirements that user agents must follow for an implementation to conform to this specification. The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in Keywords for use in RFCs to indicate requirement levels [RFC2119]. 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.

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.

Important Terms

Placeholder for glossary

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

Mapping WAI-ARIA to Accessibility APIs

General rules for exposing WAI-ARIA semantics

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

Conflicts between native markup semantics and WAI-ARIA

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

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

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.

General Rules

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

Role Mapping Table

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 roles in digital publishing map to platform accessibility APIs based on their native host language semantics and when WAI-ARIA roles are applied. This section refers directly to the Core Accessibility API Mappings specification.

It is unclear whether the roles: doc-glossref, doc-biblioref, doc-locator, doc-noteref will all stay in the specification as these are all forms of links. One possible solution is to use @rel however that does not exist in SVG and currently thre are no platform accessibility API mappings for @rel. Additionally the cognitive accssibility task force has a need to add semantics to links as well. Consequently, the existing of these roles and/or their accessibility API mappings is still an issue to be addressed.

There are a number of roles mappings that are localized. The group needs to look into localizing for non-English languages.

There are a number of Mac OSX subroles that need to be addressed and they are currently marked as TBD.

Table describing mapping of WAI-ARIA roles to accessibility APIs.
WAI-ARIA Role MSAA + IAccessible2 Role + Other IAccessible2 Features UIA Control Type + Other Features ATK/AT-SPI Role AXAPI[Note 1]
doc-abstract

ROLE_SYSTEM_GROUPING

IAccessible2: Object attribute xml-roles:doc-abstract.

  • Expose as text string 'doc-abstract' in AriaRole.
  • Control type/role is 'abstract'.

Expose ROLE_PANEL and object attribute xml-roles:doc-abstract.

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'abstract'
doc-acknowledgments

IAccessible2: Object attribute xml-roles:doc-acknowledgments.

  • Expose as text string 'doc-acknowledgments' in AriaRole.
  • Control type/role is 'acknowledgements'

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

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'acknolwedgements'
doc-afterword

IAccessible2: Object attribute xml-roles:doc-afterword.

  • Expose as text string 'doc-afterword' in AriaRole.
  • Control type/role is 'afterword'.

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

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'afterword'
doc-appendix

IAccessible2: Object attribute xml-roles:doc-appendix.

  • Expose as text string 'doc-appendix' in AriaRole.
  • Control type/role is 'appendix'.

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

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'appendix'
doc-biblioentry

IAccessible2: Object attribute xml-roles:doc-biblioentry.

  • Expose as text string 'doc-biblioentry' in AriaRole.
  • Control type/role is 'bibliography entry'.

Expose ROLE_PANEL and object attribute xml-roles:doc-bilioentry.

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'bibliography entry'
doc-bibliography

IAccessible2: Object attribute xml-roles:doc-bibliography.

  • Expose as text string 'doc-bibliography' in AriaRole.
  • Control type/role is 'bibliography'.

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

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'bibliography'
doc-biblioref

IAccessible2: Object attribute xml-roles:doc-biblioref.

ROLE_SYSTEM_LINK + STATE_LINKED

Also, expose STATE_LINKED on all descendants

IAccessible2: Use AccessibleHypertext interface
  • Expose as text string 'doc-biblioref' in AriaRole.
  • Control type/role is 'bibliography references'.

Expose ROLE_LINK and object attribute xml-roles:doc-biblioref.

AXRole: AXLink
AXSubrole: nil
AXRoleDescription: 'bibliography reference'
doc-chapter

IAccessible2: Object attribute xml-roles:chapter.

  • Expose as text string 'doc-chapter' in AriaRole.
  • Control type/role is 'chapter'.

Expose ROLE_LANDMARK and object attribute xml-roles:chapter.

AXRole: AXGroup
d AXSubrole: ? TBD
AXRoleDescription: 'chapter'
doc-colophon

ROLE_SYSTEM_GROUPING

IAccessible2: Object attribute xml-roles:doc-colophon.

  • Expose as text string 'doc-colophon' in AriaRole.
  • Control type/role is 'colophon'.

Expose ROLE_PANEL and object attribute xml-roles:doc-colophon.

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'colophon'
doc-conclusion

IAccessible2: Object attribute xml-roles:doc-conclusion.

  • Expose as text string 'doc-conclusion' in AriaRole.
  • Control type/role is 'conclusion'.

Expose ROLE_PANEL and object attribute xml-roles:doc-conclusion.

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'conclusion'
doc-cover

IAccessible2: Object attribute xml-roles:doc-cover.

  • Expose as text string 'doc-cover' in AriaRole.
  • Control type/role is 'cover'.

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

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'cover'
doc-credit

ROLE_SYSTEM_GROUPING

IAccessible2: Object attribute xml-roles:doc-credit.

  • Expose as text string 'doc-credit' in AriaRole.
  • Control type/role is 'credit'.

Expose ROLE_PANEL and object attribute xml-roles:doc-credit.

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'credit'
doc-cover

IAccessible2: Object attribute xml-roles:doc-credits.

  • Expose as text string 'doc-credits' in AriaRole.
  • Control type/role is 'credits'.

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

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'credits'
doc-dedication

ROLE_SYSTEM_GROUPING

IAccessible2: Object attribute xml-roles:doc-dedication.

  • Expose as text string 'doc-dedication' in AriaRole.
  • Control type/role is 'dedication'.

Expose ROLE_PANEL and object attribute xml-roles:doc-dedication.

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'dedication'
doc-epigraph

ROLE_SYSTEM_GROUPING

IAccessible2: Object attribute xml-roles:doc-epigraph.

  • Expose as text string 'doc-epigraph' in AriaRole.
  • Control type/role is 'epigraph'.

Expose ROLE_PANEL and object attribute xml-roles:doc-epigraph.

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'epigraph'
doc-epilogue

IAccessible2: Object attribute xml-roles:doc-epilogue.

  • Expose as text string 'doc-epilogue' in AriaRole.
  • Control type/role is 'epilogue'.

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

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'epilogue'
doc-errata

IAccessible2: Object attribute xml-roles:doc-errata.

  • Expose as text string 'doc-errata' in AriaRole.
  • Control type/role is 'errata'. Localized Control Type is based on AriaRole.

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

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'errata'
doc-example

ROLE_SYSTEM_GROUPING

IAccessible2: Object attribute xml-roles:doc-example.

  • Expose as text string 'doc-example' in AriaRole.
  • Control type/role is 'example'.

Expose ROLE_PANEL and object attribute xml-roles:doc-example.

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'example'
doc-footnote

ROLE_SYSTEM_GROUPING

IA2_ROLE_FOOTNOTE
  • Expose as text string 'doc-footnote' in AriaRole.
  • Control type/role is 'footnote'.

Expose ROLE_FOOTNOTE and object attribute xml-roles:doc-footnote.

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'footnote'
doc-footnotes

IAccessible2: Object attribute xml-roles:doc-footnotes.
  • Expose as text string 'doc-footnotes' in AriaRole.
  • Control type/role is 'footnotes'.

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

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'footnotes'
doc-foreward

IAccessible2: Object attribute xml-roles:doc-foreward.
  • Expose as text string 'doc-foreward' in AriaRole.
  • Control type/role is 'foreward'.

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

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'foreward'
doc-glossary

IAccessible2: Object attribute xml-roles:doc-glossary.
  • Expose as text string 'glossary' in AriaRole.
  • Control type/role is 'glossary'.

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

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'glossary'
doc-glossref

IAccessible2: Object attribute xml-roles:doc-glossref.

ROLE_SYSTEM_LINK + STATE_LINKED

Also, expose STATE_LINKED on all descendants

IAccessible2: Use AccessibleHypertext interface
  • Expose as text string 'doc-glossref' in AriaRole.
  • Control type/role is 'glossary reference'.

Expose ROLE_LINK and object attribute xml-roles:doc-glossref.

AXRole: AXLink
AXSubrole: nil
AXRoleDescription: 'glossary reference'
doc-index

IAccessible2: Object attribute xml-roles:doc-index.
  • Expose as text string 'doc-index' in AriaRole.
  • Control type/role is 'index'.

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

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'index'
doc-introduction

IAccessible2: Object attribute xml-roles:doc-indroduction.
  • Expose as text string 'doc-introduction' in AriaRole.
  • Control type/role is 'introduction'.

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

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'introduction'
doc-locator

IAccessible2: Object attribute xml-roles:doc-locator.

ROLE_SYSTEM_LINK + STATE_LINKED

Also, expose STATE_LINKED on all descendants

IAccessible2: Use AccessibleHypertext interface
  • Expose as text string 'doc-locator' in AriaRole.
  • Control type/role is 'locator HyperLink'.

Expose ROLE_LINK and object attribute xml-roles:doc-locator.

AXRole: AXLink
AXSubrole: nil
AXRoleDescription: 'backward reference'
doc-noteref

IAccessible2: Object attribute xml-roles:doc-noteref.

ROLE_SYSTEM_LINK + STATE_LINKED

Also, expose STATE_LINKED on all descendants

IAccessible2: Use AccessibleHypertext interface
  • Expose as text string 'doc-noteref' in AriaRole.
  • Control type/role is 'note reference'.

Expose ROLE_LINK and object attribute xml-roles:doc-noteref.

AXRole: AXLink
AXSubrole: nil
AXRoleDescription: 'note reference'
doc-notice

IAccessible2: Object attribute xml-roles:doc-notice.
  • Expose as text string 'doc-notice' in AriaRole.
  • Control type/role is 'notice'.

Expose ROLE_PANEL and object attribute xml-roles:doc-notice.

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'notice'
doc-pagebreak

IAccessible2: Object attribute xml-roles:doc-pagebreak.
  • Expose as text string 'doc-pagebreak' in AriaRole.
  • Control type/role is 'pagebreak'.

Expose ROLE_STATIC and object attribute xml-roles:doc-pagebreak.

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'page break'
doc-pagelist

IAccessible2: Object attribute xml-roles:navigation.
  • Expose as text string 'doc-pagelist' in AriaRole.
  • Control type/role is 'page list'.

Expose ROLE_LANDMARK and object attribute xml-roles:navigation.

AXRole: AXGroup
AXSubrole: ? AXLandmarkNavigation
AXRoleDescription: 'page list'
doc-part

IAccessible2: Object attribute xml-roles:doc-part.
  • Expose as text string 'doc-part' in AriaRole.
  • Control type/role is 'part'.

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

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'part'
doc-preface

IAccessible2: Object attribute xml-roles:doc-preface.
  • Expose as text string 'doc-preface' in AriaRole.
  • Control type/role is preface.

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

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'preface'
doc-preface

IAccessible2: Object attribute xml-roles:doc-prologue.
  • Expose as text string 'doc-prologue' in AriaRole.
  • Control type/role is 'prologue'.

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

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'prologue'
doc-pullquote

IAccessible2: Object attribute xml-roles:doc-pullquote.
  • Expose as text string 'doc-pullquote' in AriaRole.
  • Control type/role is 'pullquote'.

Expose ROLE_PANEL and object attribute xml-roles:doc-pullquote.

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'pullquote'
doc-qna

ROLE_SYSTEM_GROUPING

IAccessible2: Object attribute xml-roles:doc-qna.
  • Expose as text string 'doc-qna' in AriaRole.
  • Control type/role is 'questions and answers'.

Expose ROLE_PANEL and object attribute xml-roles:doc-qna.

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'questions and answers'
doc-subtitle

IAccessible2: Object attribute xml-roles:doc-subtitle.
  • Expose as text string 'doc-subtitle' in AriaRole.
  • Control type/role is 'subtitle'.

Expose ROLE_STATIC and object attribute xml-roles:doc-subtitle.

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'subtitle'
doc-tip

IAccessible2: Object attribute xml-roles:doc-tip.
  • Expose as text string 'doc-tip' in AriaRole.
  • Control type/role is 'tip'.

Expose ROLE_PANEL and object attribute xml-roles:doc-tip.

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'tip'
doc-title

IAccessible2: Object attribute xml-roles:doc-title.
  • Expose as text string 'doc-title' in AriaRole.
  • Control type/role is 'title'.

Expose ROLE_PANEL and object attribute xml-roles:doc-title.

AXRole: AXGroup
AXSubrole: ? TBD
AXRoleDescription: 'title'
doc-toc Expose as navigation role as specified in the [[!CORE-AAM]]. Expose as navigation role as specified in the [[!CORE-AAM]]. Expose as navigation role as specified in the [[!CORE-AAM]]. Expose as navigation role as specified in the [[!CORE-AAM]].

[Note 2] This specification does not currently contain guidance for when user agents should fire system alert events. Some guidance may be added to the specification at a later date but it will be a recommendation (should), not a requirement (must).

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

Special Processing Requiring Additional Computation

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-AAM]] specification with the following modifications for the host language:

  1. Replace step 2D with the following:
    Otherwise, if performing a text alternative computation for an accessible name and the current node's provides a descendant <title> element, return the title text alternative as a flat string, unless the element is marked as presentational (role="presentation" or role="none"). If performing a text alternative computation for an accessible description, and the current node provides a descendant <desc> return the description text alternative an accessible description computation attribute as presentational (role="presentation" or role="none").
  2. In step 2F skip step iii of Text Alternative Computation

Widget Values

User agents MUST conform to the Widget Values accessibility API computational requirements in [[!CORE-AAM]].

Relations

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

Group Position

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

Actions

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

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]] Events mappings.

Special Document Handling Procedures

User agents MUST conform to the Special Document Handling Procedures in [[!CORE-AAM]].

Appendices

References

This section is informative.

Placeholder for references