Copyright © 2024-2025 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.
This document describes how user agents should expose semantics of PDF content to accessibility APIs. This helps users with disabilities to obtain and interact with information using assistive technologies. Documenting these mappings promotes interoperable exposure of roles, states, properties, and events implemented by accessibility APIs and helps to ensure that this information appears in a manner consistent with author intent.
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 standards and drafts index.
The Accessible Rich Internet Applications Working Group seeks feedback on any aspect of the specification. When submitting feedback, please consider issues in the context of the companion documents. To comment, file an issue in the W3C pdf-aam GitHub repository. If this is not feasible, send email to public-aria@w3.org (comment archive). In-progress updates to the document may be viewed in the publicly visible editors' draft.
This document was published by the Accessible Rich Internet Applications Working Group as an Editor's Draft.
Publication as an Editor's 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 a 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 that 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 18 August 2025 W3C Process Document.
This section is non-normative.
PDF pages do not necessarily include semantic markup, which occurs in PDF files via the elements of Tagged PDF, including PDF structure elements, structure attributes, and property lists associated with marked content sequences. These features are defined in PDF’s specification, currently ISO 32000-2, in clauses 14.6 – 14.9. Tagged PDF was introduced to PDF with PDF 1.4 in 2001.
This specification defines how PDF user agents (commonly referred to as “PDF processors” in ISO standards for PDF technology) respond to and expose PDF-object to be named (structure elements, structure attributes, or property lists associated with marked content, etc., as defined in ISO 32000-2 clauses 14.7–14.9).
Users often access PDF content using assistive technologies that rely on platform accessibility API to obtain and interact with information on a PDF page. This specification is part of the following suite of accessibility API mapping specifications for content rendered by user agents:
This section is non-normative.
can represent any or all of the following: Structure Element, Structure Attribute, Property list associated with marked content, or Associated File(s)
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 MUST NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
Normative sections provide requirements that user agents and assistive technologies MUST follow for an implementation to conform to this specification.
Non-normative (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.
Unless indicated otherwise, a PDF-object to be named with default Accessible Rich Internet Applications (WAI-ARIA) 1.2 semantics MUST be exposed to the platform accessibility APIs according to the relevant WAI-ARIA mappings defined in the Core Accessibility API Mappings 1.2 specification. Where a PDF-object to be named has equivalent semantics to a WAI-ARIA role, user agents MUST expose such semantic information to the platform for the WAI-ARIA accessibility APIs in a way that conforms to the WAI-ARIA semantics in the Core Accessibility API Mappings 1.2.
In some cases, features present in a PDF may not map to a WAI-ARIA role specified in the Core AAM 1.2. In such cases a relevant HTML Accessibility API Mapping may exist. In those cases, a PDF-object to be named is mapped to that HTML Accessibility API. Where a PDF-object to be named has equivalent semantics to an HTML element, but not a WAI-ARIA role, user agents MUST expose such semantic information to the platform for HTML accessibility APIs in a way that conforms to the HTML Accessibility API Mappings 1.0.
Where a PDF-object to be named does not have any default HTML or WAI-ARIA semantics, the applicable mapping for each platform accessibility API is defined by this specification.
A minimum role is the equivalent WAI-ARIA role a PDF-object to be named will map to if the element does not have a more specific implicit role or platform role mappings, e.g., a non-generic role. Minimum roles help ensure that users of assistive technologies get the best possible experience for valid PDF-object to be named where otherwise a role would not be exposed.
A minimum role is provided when all of the following conditions are true:
none, presentation, or generic;
none computed role;
The HTML Attribute State and Property Mappings section identifies the specific global attributes which would require an element map to a minimum role. When these conditions are met, the browser MUST expose an object using the mappings defined in CORE-AAM for the specified minimum role. If the element has multiple attributes specified which require a minimum role be returned as the computed role for the element, prioritize the more specific role in the ARIA taxonomy.
PDF-object to be named with implicit WAI-ARIA role semantics MUST be mapped to platform accessibility APIs according to the identified WAI-ARIA role mapping as defined in the Core AAM 1.2 specification.
Where a PDF-object to be named is indicated as having “No corresponding (WAI-ARIA) role”, or is mapped to the generic role, user agents MUST NOT expose the
aria-roledescription property value in the accessibility tree unless the element has an explicit, conforming role attribute value which
WAI-ARIA 1.2 does not prohibit the use of aria-roledescription.
Some HTML elements expose implicit WAI-ARIA roles depending on whether they have been provided an accessible name. How an element participates in the computation of its own or another element’s accessible name and/or accessible description is described in the Accessible Name and Description Computation section of this document.
TBD. Should we duplicate or cross-reference this content from the corresponding Core-AAM section?
TBD. Should we duplicate or cross-reference this content from the corresponding Core-AAM section?
TBD. Should we duplicate or cross-reference this content from the corresponding Core-AAM section?
| ARIA Specification |
Role: generic
|
|---|---|
| Analogous HTML Element |
Role: body
|
| MSAA + IAccessible2 | Use WAI-ARIA mapping |
| UIA | Use WAI-ARIA mapping |
| ATK/AT-SPI | Use WAI-ARIA mapping |
| AX API[Note 1] | Use WAI-ARIA mapping |
| Notes: |
Note from PDFa: only processor instructions
|
| ARIA Specification |
Role: generic
|
|---|---|
| Analogous HTML Element | Use WAI-ARIA mapping |
| MSAA + IAccessible2 | Use WAI-ARIA mapping |
| UIA | Use WAI-ARIA mapping |
| ATK/AT-SPI | Use WAI-ARIA mapping |
| AX API[Note 1] | Use WAI-ARIA mapping |
| Notes: |
Note from PDFa:
Added note - question for the group... A screen reader shouldn't "announce" when it hits the first Document tag but should it "announce" when it hits "nested" (subsequent)
Document tags, to tell someone they are in a "second" document? AND... the same question applies to Document Fragment, too. If "Yes," how do we indicate that in the AAM?)
|
| ARIA Specification |
Role: region IF there is an accessible name. Otherwise use generic
|
|---|---|
| Analogous HTML Element |
Role: section
|
| MSAA + IAccessible2 | Use WAI-ARIA mapping |
| UIA | Use WAI-ARIA mapping |
| ATK/AT-SPI | Use WAI-ARIA mapping |
| AX API[Note 1] | Use WAI-ARIA mapping |
| Notes: |
Note from PDFa: To calculate the "accessible name": The first Hn descendant that is not a descendant of another Sect element provides the accessible name.
|
| ARIA Specification |
Role: paragraph
|
|---|---|
| Analogous HTML Element | Use WAI-ARIA mapping |
| MSAA + IAccessible2 | Use WAI-ARIA mapping |
| UIA | Use WAI-ARIA mapping |
| ATK/AT-SPI | Use WAI-ARIA mapping |
| AX API[Note 1] | Use WAI-ARIA mapping |
| Notes: | Use WAI-ARIA mapping |
| ARIA Specification |
Role: ARIA heading (role)
Property: ARIA level (property)
|
|---|---|
| Analogous HTML Element | Use WAI-ARIA mapping |
| MSAA + IAccessible2 | Use WAI-ARIA mapping |
| UIA | Use WAI-ARIA mapping |
| ATK/AT-SPI | Use WAI-ARIA mapping |
| AX API[Note 1] | Use WAI-ARIA mapping |
| Notes: |
Note from PDFa: heading with the aria-level property set to the number in the element's tag name.
|
| ARIA Specification | No corresponding role |
|---|---|
| Analogous HTML Element |
Role: label
|
| MSAA + IAccessible2 | Use HTML-AAM mapping |
| UIA | Use HTML-AAM mapping |
| ATK/AT-SPI | Use HTML-AAM mapping |
| AX API[Note 1] | Use HTML-AAM mapping |
| Notes: |
|
| ARIA Specification |
Role: generic
|
|---|---|
| Analogous HTML Element | Use WAI-ARIA mapping |
| MSAA + IAccessible2 | Use WAI-ARIA mapping |
| UIA | Use WAI-ARIA mapping |
| ATK/AT-SPI | Use WAI-ARIA mapping |
| AX API[Note 1] | Use WAI-ARIA mapping |
| Notes: | Label types, especially for lists in UA-2, will receive further guidance at a future time. |
| ARIA Specification |
Role: term
|
|---|---|
| Analogous HTML Element |
Role: dt
|
| MSAA + IAccessible2 | Use WAI-ARIA mapping |
| UIA | Use WAI-ARIA mapping |
| ATK/AT-SPI | Use WAI-ARIA mapping |
| AX API[Note 1] | Use WAI-ARIA mapping |
| Notes: |
Note from PDFa: Use WAI-ARIA mapping - BUT - "computed role" may change
|
| ARIA Specification |
Role: link
|
|---|---|
| Analogous HTML Element |
Role: a (represents a hyperlink)
Role: area (represents a hyperlink)
|
| MSAA + IAccessible2 | Use WAI-ARIA mapping |
| UIA | Use WAI-ARIA mapping |
| ATK/AT-SPI | Use WAI-ARIA mapping |
| AX API[Note 1] | Use WAI-ARIA mapping |
| Notes: |
Note from PDFa: both "a" and "area" point to "link" in ARIA and say to use WAI-ARIA mapping
|
| ARIA Specification |
generic
|
|---|---|
| Analogous HTML Element |
Role: a (represents a hyperlink)
Role: area (represents a hyperlink)
|
| MSAA + IAccessible2 | Use WAI-ARIA mapping |
| UIA | Use WAI-ARIA mapping |
| ATK/AT-SPI | Use WAI-ARIA mapping |
| AX API[Note 1] | Use WAI-ARIA mapping |
| Notes: |
Note from PDFa: Use WAI-ARIA mapping
|
| ARIA Specification |
generic
|
|---|---|
| Analogous HTML Element | Use WAI-ARIA mapping |
| MSAA + IAccessible2 | Use WAI-ARIA mapping |
| UIA | Use WAI-ARIA mapping |
| ATK/AT-SPI | Use WAI-ARIA mapping |
| AX API[Note 1] | Use WAI-ARIA mapping |
| Notes: |
Note from PDFa: Exposed by platform specific underline text styles.
|
TBD. Should we duplicate or cross-reference this content from the corresponding Core-AAM section?
TBD. Should we duplicate or cross-reference this content from the corresponding Core-AAM section?
TBD. Should we duplicate or cross-reference this content from the corresponding Core-AAM section?
This specification introduces no new security considerations.
TBD. Should we duplicate or cross-reference this content from the corresponding Core-AAM section?
This section is non-normative.
The following people contributed to the development of this document.
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.