Enabling users of assistive technologies to find their way through Web content requires embedding semantic metadata about Web document structural divisions. This is particularly important for structural divisions of long-form documents and goes along with embedding semantic metadata about Web-application widgets and behaviors for assistive technologies. This specification defines a set of WAI-ARIA roles specific to helping users of assistive technologies navigate through such long-form documents.
This document is part of the WAI-ARIA suite described in the WAI-ARIA Overview.
Status of This Document
This section describes the status of this document at the time of its publication. Other documents may supersede this document. 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/.
To comment on this document, file an issue in the W3C dpub-aria GitHub repository. If this is not feasible, send email to public-aria@w3.org (comment archive). Comments received on the DPub-ARIA 1.0 Recommendation cannot result in changes to this version of the specification, but may be addressed in errata or future versions of DPub-ARIA. The Working Group may not make formal responses to comments but future work undertaken by the Working Group may address comments received on this document. In-progress updates to the document may be viewed in the publicly visible editors' draft.
This document has been reviewed by W3C Members, by software developers, and by other W3C
groups and interested parties, and is endorsed by the Director as a W3C Recommendation.
It is a stable document and may be used as reference material or cited from another
document. W3C's role in making the Recommendation is to draw attention to the
specification and to promote its widespread deployment. This enhances the functionality
and interoperability of the Web.
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.
WAI-ARIA is a technical specification that defines a common host language semantic accessibility API and framework that enables web browsers to map the accessibility semantics in web content to platform-specific accessibility APIs. This enables web content to be interoperable with platform assistive technologies similar to native platform applications without platform dependencies.
This specification is a modular extension of WAI-ARIA designed for the digital publishing industry. The goals of this specification include:
Expanding [wai-aria-1.1] to produce structural semantic extensions to accommodate the digital publishing industry.
Align with a new governance model for modularization and extensions to WAI-ARIA.
Provide structural semantics extensions that will support both assistive technologies and enable semantic navigation, styling and interactive features used by readers.
This specification defines a module of WAI-ARIA for digital publishing, including roles, states, properties and values. It impacts several audiences:
User agents that process content containing WAI-ARIA and Digital Publishing WAI-ARIA features;
Assistive technologies that provide specialized reading experiences to users with disabilities;
Authors of digital publications;
Authoring tools that help authors create conforming digital publications; and
Conformance checkers, that verify appropriate use of WAI-ARIA and this Digital Publishing WAI-ARIA module.
Each conformance requirement indicates the audience to which it applies.
Although this specification is applicable to the above audiences, it is not specifically targeted to, nor is it intended to be the sole source of information for, any of these audiences. In the future, additional documents will be created to assist authors in applying these WAI-ARIA semantics for the publishing industry and to define how the information in this document is mapped to platform accessibility APIs.
This module builds on the general User Agent support principles defined in [wai-aria-1.1] by also providing the ability for user agents to enhance the general user interface presented to readers.
The Digital Publishing WAI-ARIA module follows the model for co-evolution of WAI-ARIA and host languages defined in [wai-aria-1.1]. It is intended to augment semantics in supporting languages like [html5], [SVG2] and EPUB, or to be used as an accessibility enhancement technology in other markup-based languages that do not explicitly include support for ARIA. It clarifies semantics to assistive technologies when authors create new types of objects, via style and script, that are not yet directly supported by the language of the page, because the invention of new types of objects is faster than standardized support for them appears in web languages.
It is not appropriate to create objects with style and script when the host language provides a semantic element for that type of objects. While WAI-ARIA can improve the accessibility of these objects, accessibility is best provided by allowing the user agent to handle the object natively. For example, it is not better to use a heading role on a div element than it is to use a native heading element, such as an h1.
It is expected that, over time, host languages will evolve to provide semantics for objects that currently can only be declared with this specification. This is natural and desirable, as one goal of WAI-ARIA is to help stimulate the emergence of more semantic and accessible markup. When native semantics for a given feature become available, it is appropriate for authors to use the native feature and stop using this module for that feature. Legacy content may continue to use the Digital Publishing WAI-ARIA module, however, so the need for user agents to support it remains.
While specific features of this module may lose importance over time, the general possibility of the Digital Publishing WAI-ARIA module to add semantics to web pages or open web based standards, such as EPUB, is expected to be a persistent need. Host languages may not implement all the semantics this module provides, and various host languages may implement different subsets of the features. New types of objects are continually being developed, and one goal of this specification is to provide a way to make such objects accessible, because authoring practices often advance faster than host language standards. In this way, this module and host languages both evolve together but at different rates.
Some host languages exist to create semantics for features other than the user interface. For example, SVG expresses the semantics behind production of graphical objects, not of user interface components that those objects may represent. Host languages such as these might, by design, not provide native semantics that map to this specification's features. In these cases, the Digital Publishing WAI-ARIA module could be adopted as a long-term approach to add semantic information to these host languages.
Many of the requirements in the definitions of the WAI-ARIA and Digital Publishing WAI-ARIA roles, states and properties can be checked automatically during the development process, similar to other quality control processes used for validating code. To assist authors who are creating digital publications, such as EPUB, can compare the semantic structure of Digital Publishing WAI-ARIA roles from the DOM to that defined in this specification and notify the author of errors or simply create templates that enforce that structure.
The accessibility of interactive content cannot be confirmed by static checks alone. Developers of interactive content should test for device-independent access to widgets and applications, and should verify accessibility API access to all content and changes during user interaction.
Programmatic access to accessibility semantics is essential for assistive technologies. For more information, refer to the Assistive Technologies section in [wai-aria-1.1].
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 are
to be interpreted as described in [RFC2119].
This specification indicates whether a section is normative or informative. Classifying a section as normative or informative 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 authors, user agents and assistive technologies MUST follow for an implementation to conform to 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.
relies on services provided by a user agent to retrieve and render Web content
works with a user agent or web content itself through the use of APIs, and
provides services beyond those offered by the user agent to facilitate user interaction with web content by people with disabilities
This definition may differ from that used in other documents.
Examples of assistive technologies that are important in the context
of this document include the following:
screen magnifiers, which are used to enlarge and improve the visual readability of rendered text and images;
screen readers, which are most-often used to convey information through synthesized speech or a refreshable Braille display;
text-to-speech software, which is used to convert text into synthetic speech;
speech recognition software, which is used to allow spoken control and dictation;
alternate input technologies (including head pointers, on-screen keyboards, single switches, and sip/puff devices), which are used to simulate the keyboard;
alternate pointing devices, which are used to simulate mouse pointing and clicking.
Attribute
In this specification, attribute is used as it is in markup languages. Attributes are structural features added to elements to provide information about the states and properties of the object represented by the element.
Class
A set of instance objects that share similar characteristics.
Element
In this specification, element is used as it is in markup languages. Elements are the structural elements in markup language that contains the data profile for objects.
Event
A programmatic message used to communicate discrete changes in the state of an object to other objects in a computational system. User input to a web page is commonly mediated through abstract events that describe the interaction and can provide notice of changes to the state of a document object. In some programming languages, events are more commonly known as notifications.
Informative
Content provided for information purposes and not required for conformance. Content required for conformance is referred to as normative.
Normative
Required for conformance. By contrast, content identified as informative or "non-normative" is not required for conformance.
Object
In the context of user interfaces, an item in the perceptual user experience, represented in markup languages by one or more elements, and rendered by user agents.
In the context of programming, the instantiation of one or more classes and interfaces which define the general characteristics of similar objects. An object in an accessibility API may represent one or more DOM objects. Accessibility APIs have defined interfaces that are distinct from DOM interfaces.
Ontology
A description of the characteristics of classes and how they relate to each other.
Property
Attributes that are essential to the nature of a given object, or that represent a data value associated with the object. A change of a property may significantly impact the meaning or presentation of an object. Certain properties (for example, aria-multiline) are less likely to change than states, but note that the frequency of change difference is not a rule. A few properties, such as aria-activedescendant, aria-valuenow, and aria-valuetext are expected to change often. See clarification of states versus properties.
Role
Main indicator of type. This semantic association allows tools to present and support interaction with the object in a manner that is consistent with user expectations about other objects of that type.
Semantics
The meaning of something as understood by a human, defined in a way that computers can process a representation of an object, such as elements and attributes, and reliably represent the object in a way that various humans will achieve a mutually consistent understanding of the object.
State
A state is a dynamic property expressing characteristics of an object that may change in response to user action or automated processes. States do not affect the essential nature of the object, but represent data associated with the object or user interaction possibilities. See clarification of states versus properties.
Taxonomy
A hierarchical definition of how the characteristics of various classes relate to each other, in which classes inherit the properties of superclasses in the hierarchy. A taxonomy can comprise part of the formal definition of an ontology.
User Agent
Any software that retrieves, renders and facilitates end user interaction with Web content. This definition may differ from that used in other documents.
Widget
Discrete user interface object with which the user can interact. Widgets range from simple objects that have one value or operation (e.g., check boxes and menu items), to complex objects that contain many managed sub-objects (e.g., trees and grids).
This section defines additions to the WAI-ARIA roletaxonomy and describes the characteristics and properties of all roles. See ARIA Roles for descriptions of the fields provided by this module.
A section or statement that acknowledges significant contributions by persons, organizations, governments and other entities to the realization of the work.
A closing statement from the author or a person of importance, typically providing insight into how the content came to be written, its significance, or related events that have transpired since its timeline.
A link that allows the user to return to a related location in the content (e.g., from a footnote to its reference or from a glossary definition to where a term is used).
A single reference to an external source in a bibliography. A biblioentry typically provides more detailed
information than its reference(s) in the content (e.g., full title, author(s), publisher, publication date, etc.).
An acknowledgment of the source of integrated content from third-party sources, such as photos. Typically identifies the creator, copyright and any restrictions on reuse.
One of a collection of notes that occur at the end of a work, or a section within it,
that provides additional context to a referenced passage of text.
A major structural division in a work that contains a set of related sections dealing with a particular subject, narrative arc or similar encapsulated theme.
A navigational aid that provides an ordered list of links to the major sectional headings in the content. A table of contents may cover an entire work, or only a smaller section of it.
A short summary of the principle ideas, concepts and conclusions of the work, or of a section or excerpt within it.
Example 1
<sectionrole="doc-abstract"aria-label="Abstract"><p>Accessibility of web content requires semantic information about widgets, structures,
and behaviors …</p></section>
A section or statement that acknowledges significant contributions by persons, organizations, governments and other entities to the realization of the work.
Example 2
<sectionrole="doc-acknowledgments"><p>I would like to extend my sincere gratitude to … </p></section>
A closing statement from the author or a person of importance, typically providing insight into how the content came to be written, its significance, or related events that have transpired since its timeline.
Example 3
<sectionrole="doc-afterword"><h1>Afterword: Why I Wrote This Book</h1>
…
</section>
A link that allows the user to return to a related location in the content (e.g., from a footnote to its reference or from a glossary definition to where a term is used).
Example 5
<aside id="fn01" role="doc-footnote">
<arole="doc-backlink"href="#fnref01">1.</a>
Additional results ofthis study and
similar studies can be found at …
</aside>
A single reference to an external source in a bibliography. A biblioentry typically provides more detailed
information than its reference(s) in the content (e.g., full title, author(s), publisher, publication date, etc.).
Authors MUST ensure that elements with role doc-biblioentry are contained in, or owned, by an element with the role list.
Example 6
<sectionrole="doc-bibliography"><h1>Cited Works</h1><divrole="list"><prole="doc-biblioentry"id="b8cab5dd-bc24-459c-9858-7afa9da69b64">
John Steinbeck, The Grapes of Wrath (New York: The Viking Press, 1939)
</p></div>
…
</section>
Example 7
<sectionrole="doc-bibliography"><h1>Select Bibliography</h1><ul><lirole="doc-biblioentry"id="faulkner-dying">
William Faulkner, As I Lay Dying (New York: Jonathan Cape & Harrison Smith, 1930)
</li></ul>
…
</section>
An acknowledgment of the source of integrated content from third-party sources, such as photos. Typically identifies the creator, copyright and any restrictions on reuse.
Example 14
<prole="doc-credit">
Page 62, Table 3.1 from <cite>“Economic Foundations of Cost-Effectiveness Analysis”</cite>
by A. M. Garber and C. E. Phelps …
</p>
One of a collection of notes that occur at the end of a work, or a section within it,
that provides additional context to a referenced passage of text.
Authors MUST ensure that elements with roledoc-endnote are contained in, or owned, by an element with the role list.
Example 17
<sectionrole="doc-endnotes"><h2>Notes</h2><ol><liid="6baa07af"role="doc-endnote">Additional results of this study can be found at … </li><liid="7b2c0555"role="doc-endnote">…</li>
…
</ol></section>
Example 18
<sectionrole="doc-endnotes"><h2>Notes</h2><sectionid="ch1-notes"><h3>Chapter 1</h3><divrole="list"><pid="6baa07af"role="doc-endnote">1. Additional results of this study can be found at … </p><divid="7b2c0555"role="doc-endnote"><p>2. The primary source of infomation …</p><pclass="note-cont">In the case of secondary studies …</p></div>
…
</div></section></section>
A collection of notes at the end of a work or a section within it.
Note that the doc-endnotesrole is never applied directly to the list of endnotes. See
the doc-endnote role for more information.
Example 19
<sectionrole="doc-endnotes"><h2>Notes</h2><ol><liid="6baa07af"role="doc-endnote">Additional results of this study can be found at … </li><liid="7b2c0555"role="doc-endnote">…</li>
…
</ol></section>
A quotation set at the start of the work or a section that establishes the theme or sets the mood.
Example 20
<blockquoterole="doc-epigraph"><p>“Would you tell me please, which way I ought to go from here?”</p><p>“That depends a good deal on where you want to get to,” said the cat.</p></blockquote>
Ancillary information, such as a citation or commentary, that provides additional context to a referenced passage of text.
The doc-footnoterole is only for representing individual notes that occur within the body of a work.
For collections of notes that occur at the end of a section, see doc-endnotes.
Example 24
<aside id="6baa07af" role="doc-footnote">
* Additional results ofthis study and similar studies can be found at …
</aside>
A brief dictionary of new, uncommon or specialized terms used in the content.
Example 26
<dlrole="doc-glossary">
…
<dtid="bcc0f155"role="term">Credit default swap</dt><ddrole="definition">
A credit default swap effectively insures against
default by a borrower.
</dd>
…
</dl>
Notifies the user of consequences that might arise from an action or event. Examples include warnings, cautions and dangers.
Example 31
<section role="doc-notice">
<imgsrc="warning.png"alt="warning icon"/><p>Just because you can include a font doesn’t mean you should.
Think carefully about readability. Also, be respectful of intellectual property.
There are many excellent free open source fonts available.</p></section>
Authors SHOULD include a label when the notice needs to be navigable to.
Example 32
<divrole="doc-notice"aria-label="Explosion Risk"><p><em>Danger!</em> Mixing reactive materials may cause an explosion.</p></div>
A major structural division in a work that contains a set of related sections dealing with a particular subject, narrative arc or similar encapsulated theme.
A distinctively placed or highlighted quotation from the current content designed to draw attention to a topic or highlight a key point.
Unlike a passage quoted from another source, a pullquote is a direct repetition of text in the current document. As a result, authors must ensure that the presentational occurrence is hidden from users of assistive technologies (e.g., using the aria-hidden attribute).
The following example shows the identification of a pullquote that will be presented elsewhere (e.g., via a script). In this case, the pullquote is not hidden as the marked text is not presentational.
Example 38
<p>… I may die, but first you, my tyrant and tormentor, shall curse the sun that gazes on your misery.
<spanid="pq01"role="doc-pullquote">Beware, for I am fearless and therefore powerful.</span>
I will watch with the wiliness of a snake, that I may sting with its venom. … </p>
The next example shows a pullquote that duplicates the text. This quote is hidden because it is for presentational purposes only.
Example 39
<p>… Better habits pave the way to growth, and growth leads to greater happiness.</p><asiderole="doc-pullquote"aria-hidden="true">
Better habits pave the way to growth, and growth leads to greater happiness.
</aside>
A section of content structured as a series of questions and answers, such as an interview or list of frequently asked questions.
Example 40
<sectionrole="doc-qna"><h2>Interview with the Author</h2><dl><dt>Q: When did you begin writing this book?</dt><dd>A: I first got the idea …</dd>
…
</dl></section>
Helpful information that clarifies some aspect of the content or assists in its comprehension.
Example 42
<asiderole="doc-tip"><h3>Tip</h3><p>You can assign a variable a new value that is the result
of an expression involving its previous value.</p></aside>
A navigational aid that provides an ordered list of links to the major sectional headings in the content. A table of contents may cover an entire work, or only a smaller section of it.
Example 43
<navrole="doc-toc"><h1>Contents</h1><olrole="directory"><li><ahref="preface_001.xhtml">Original Transcriber’s Notes:</a></li><li><ahref="introduction_001.xhtml">ETYMOLOGY.</a></li><li><ahref="epigraph_001.xhtml">EXTRACTS (Supplied by a Sub-Sub-Librarian).</a></li><li><ahref="chapter_001.xhtml">Chapter 1. Loomings.</a></li>
…
</ol></nav>
For this specification to be advanced to Proposed Recommendation, it has to be proven that roles defined in this specification have sufficient usage by the target communities. More specifically, it has to be documented that eachDigital Publishing Role is used (at least in preliminary prototypes, not necessarily in full production yet) by two, independent document author/publisher as a means to structure document, where “usage” means:
the role attribute value is used, as defined in this specification; or, as a fallback
In the case where the epub:type attribute is used, the author/publisher should also clearly state that the plan is to replace epub:type by the ARIA role attribute when this specification is published as a Recommendation.
Furthermore, it is also required that at least two, independent authors/publishers use a comprehensive, although not necessarily complete, set of role attribute (as opposed to epub:type).
1-Mar-2016: Removed doc-footnotes and added doc-endnote and doc-endnotes to handle structural differences between standalone footnotes and lists of endnotes. Changed superclass role to landmark for doc-bibliography and added guidance about using doc-biblioentry with lists.
8-Nov-2015: Updated superclass role to group for doc-abstract, doc-footnote and doc-qna.
12-Oct-2015: Changed the "dpub-" prefix on all roles to "doc-".
30-Sept-2015: Removed the glossterm and glossdef roles. These are replaced by term and definition in [wai-aria-1.1].
The following people contributed to the development of this document.
D.1 Participants active in the DPUB-ARIA task force at the time of publication§
Michael Cooper (W3C Staff)
Heather Flanagan (Invited expert)
Matt Garrish (DAISY Consortium)
Markus Gylling (DAISY Consortium)
Ivan Herman (W3C Staff)
Deborah Kaplan (Invited expert)
George Kerscher (DAISY Consortium)
Peter Krautzberger (W3C Invited Experts)
Charles LaPierre (Benetech)
Shane McCarron (W3C Invited Experts)
Janina Sajka (Invited Expert, The Linux Foundation)
Richard Schwerdtfeger (Knowbility)
Tzviya Siegman (Wiley)
The group would like to thank all members of the DAISY and EPUB 3 working groups who developed the structural semantics vocabulary from which this module was drawn, with special thanks to Sanders Kleinfeld for his assistance analyzing the initial set of semantics for inclusion.
This publication has been funded in part with Federal funds from the U.S. Department of Education, National Institute on Disability, Independent Living, and Rehabilitation Research (NIDILRR) under contract number ED-OSE-10-C-0067. 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.