Role Attribute 1.0

An attribute to support the role classification of elements

W3C Candidate Recommendation 12 July 2012

This version:
Latest published version:
Latest editor's draft:
Previous version:
Shane McCarron, Applied Testing and Technology, Inc., shane@aptest.com
Ben Adida, Creative Commons
Mark Birbeck, webBackplane
T. V. Raman, Google, Inc.
Richard Schwerdtfeger, IBM Corporation


The Role Attribute defined in this specification allows the author to annotate markup languages with machine-extractable semantic information about the purpose of an element. Use cases include accessibility, device adaptation, server-side processing, and complex data description. This attribute can be integrated into any markup language. In particular, schema implementations are provided to facilitate with languages based upon XHTML Modularization [XHTML-MODULARIZATION11-2e].

The role attribute is necessary to support Accessible Rich Internet Applications (WAI-ARIA) [WAI-ARIA] to define roles in XML-based languages, when the languages do not define their own role attribute. Although this is the reason the Role Attribute is published by the Protocols and Formats Working Group, the attribute has more general use cases as well.

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 http://www.w3.org/TR/.

This is a Candidate Recommendation of Role Attribute 1.0 by the Protocols & Formats Working Group of the Web Accessibility Initiative. This version incorporates changes in response to public comments, as well as editorial clarifications found during group review, from the 13 January 2011 Last Call Working Draft. The Protocols and Formats Working Group received 1 comment on that version. Refer to the Issue Disposition Report for details. A history of changes to Role Attribute is available.

Exit Criteria

The Protocols and Formats Working Group intends to submit this document for consideration as a W3C Proposed Recommendation as soon as the following conditions are met:

  1. At least two user agent implementations that can demonstrate access to the role attribute and its lexical values via the DOM.
  2. At least two implementations are documented for each of the following requirements:
    1. Pass the RDFa 1.1 with Role tests;
    2. Correctly handle use of the role attribute with values from the default vocabulary;
    3. Correctly handle use of the role attribute with more than one value, including situations where some values are not from a recognized vocabulary;
    4. Correctly handle use of the role attribute with values from a custom vocabulary;
    5. Correctly handle use of the role attribute with term values, CURIE values, and IRI values.

The PFWG does not intend to include optional features in the formal testing. In general, optional or non-normative features are optional specifically because they are not expected to be interoperable.

The Role Attribute 1.0 Implementation Report contains information about the test suite, test harness, user agents being examined, and interim test results. This resource will be finalized over the course of CR testing.

The Protocols and Formats Working Group expects to collect an initial list of implementations by 1 August 2012, and targets 1 September 2012 to complete the testing process and produce the implementation report.

Implementers who wish to include their tools in the test process will find instructions to submit their implementation for consideration. The Protocols and Formats Working Group requests that initial implementations be submitted by 1 August 2012. The Working Group targets 1 September 2012 to complete the testing process and produce the final implementation report.

Features at risk

There are no features that have been identified as at risk.


The Protocols and Formats Working Group primarily seeks feedback relation to implementation of the Role Attribute, but feedback on any aspect of the specification is accepted. When submitting feedback, please consider issues in the context of the companion documents. Start with the instructions for commenting page to submit comments (preferred), or send email to public-pfwg-comments@w3.org (comment archive). Comments are requested by 24 August 2012 but will be accepted throughout the Candidate Recommendation period. In-progress updates to the document may be viewed in the publicly visible editors' draft.

Publication Information

This document was published by the Protocols and Formats Working Group as a Candidate Recommendation. This document is intended to become a W3C Recommendation. W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. This Candidate Recommendation is expected to advance to Proposed Recommendation no earlier than 24 August 2012. All feedback is welcome.

Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. 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 5 February 2004 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.

Table of Contents

1. Introduction

This section is non-normative.

This document defines an attribute designed be used to help improve the accessibility and semantic markup of documents. It has been developed in conjunction with the accessibility community and other groups to make it easier to describe the semantic meaning of document content.

An important (though not exclusive) use case for the Role Attribute is to support [WAI-ARIA]. The Role Attribute meets the requirements of Role Attribute in WAI-ARIA, Section 7.1, enabling [XML10] languages that incorporate this attribute to use WAI-ARIA roles. At time of this publication, no XML-based languages are known to use WAI-ARIA, but this attribute is important to enable planned future support (such as in SVG). By contrast, support for WAI-ARIA in [HTML5] includes an attribute named "role". The use of that attribute within [HTML5] is consistent with the definition of the role attribute in this specification, although conforming use may be limited to the use of 'TERM's within the value of the attribute.

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 words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

2.1 Document Conformance

The Role Attribute does not represent a stand-alone document type. It is intended to be integrated into other host languages such as SVG, HTML, or XHTML. A conforming Role Attribute document is a document that requires only the facilities described as mandatory in this specification and the facilities described as mandatory in its host language. Such a document must meet all the following criteria:

  1. The document must conform to the constraints expressed in its host language implementation.

  2. If the host language is an XML [XML10] markup language and is in the XHTML Namespace http://www.w3.org/1999/xhtml), there are no additional requirements. If the host language is an XML markup language and is not in the XHTML namespace, and the host language does not incorporate this attribute in 'no namespace', then the document must contain an XML namespace declaration for the Role Attribute Module namespace [XML-NAMES11]. The namespace for Role Attribute Module is defined to be http://www.w3.org/1999/xhtml. An example start tag of a root element might look like:

    <mylang xmlns="http://www.example.com/dtd/mylang" 
            xmlns:xh="http://www.w3.org/1999/xhtml" xml:lang="en" >

2.2 Host Language Conformance

When the Role Attribute is included in a host language, all of the facilities required in this specification must be included in the host language. In addition, the attribute defined in this specification must be included in the content model of the host language.

3. The Role Attribute

This specification defines the role attribute. The role attribute takes as its value one or more whitespace separated TERMorCURIEorAbsIRIs, which is defined in [RDFA-CORE]. Each component of the value maps to an IRI that corresponds to a vocabulary term that should be defined using RDF.

The datatype used for @role permits the use of a TERM, a CURIE (as defined in [RDFA-CORE]), or a full IRI. A TERM is an item from a vocabulary. The default vocabulary for use with @role is defined in [XHTML-VOCAB]. A host language may define a different default vocabulary.

The specific vocabulary terms from the default vocabulary are not included in this document. They are defined in [XHTML-VOCAB] to ease maintenance. The terms are drawn from [WAI-ARIA] and from the original work on this document by the XHTML2 Working Group.

The attribute describes the role(s) the current element plays in the context of the document. This can be used, for example, by applications and assistive technologies to determine the purpose of an element. This could allow a user to make informed decisions on which actions may be taken on an element and activate the selected action in a device independent way. It could also be used as a mechanism for annotating portions of a document in a domain specific way (e.g., a legal term taxonomy). Although the role attribute may be used to add semantics to an element, authors should use elements with inherent semantics, such as p, rather than layering semantics on semantically neutral elements, such as div role="paragraph".

The following is an example of a good, appropriate use of the role attribute:

<ul role="navigation">
    <li href="downloads">Downloads</li>
    <li href="docs">Documentation</li>
    <li href="news">News</li>

3.1 Extending the collection of roles

It is possible to define additional role values. Vocabulary authors must define such additional role values in their own vocabulary. The URI associated with that vocabulary should resolve to a resource that allows for the machine and human discovery of the definition of the roles in the vocabulary.

A good example of such a resource is the default vocabulary document at [XHTML-VOCAB]. This document uses a format compatible with the requirements of [RDFA-CORE] section 9 for machine-discoverable RDFa Initial Contexts.

4. Using Role in conjunction with RDFa

If a Host Language contains the @role attribute, then an RDFa processor processing a document written in that Host Language according to the rules of that Host Language may generate additional triples for role attributes. If these additional triples are being generated, then they must be generated as follows:

Remember that @role values are defined using the datatype TERMorCURIEorAbsIRIs. An RDFa Processor will intepret these values using the rules for that that datatype as defined in [RDFA-CORE].

A. XHTML Role Attribute Module

A.1 DTD Implementation

The DTD implementation of XHTML Role Attribute Module conforms to the requirements defined in [XHTML-MODULARIZATION11-2e]. Consequently, it provides a Qualified Names declaration module.

A.1.1 Qualified Names Module

Note that this module defines the parameter entity %xhtml-role-attrs.qname;. This entity is intended to be used in the attribute lists of elements in any host language that permits the use of the role attribute on elements in its own namespace. If a host language does not permit role in its namespace, then the host language driver should set a parameter entity %XHTML-ROLE.prefixed; to INCLUDE and a parameter entity %XHTML-ROLE.prefix; to a value that is the prefix for the XHTML Role Attribute Module attribute.

<!-- ....................................................................... -->
<!-- XHTML Role Qname Module  ............................................ -->
<!-- file: xhtml-role-qname-1.mod

     This is XHTML Role - the Role Attribute Module for XHTML.

     Copyright 2006 W3C (MIT, ERCIM, Keio), All Rights Reserved.

     This DTD module is identified by the PUBLIC and SYSTEM identifiers:

       PUBLIC "-//W3C//ENTITIES XHTML Role Attribute Qnames 1.0//EN"
       SYSTEM "http://www.w3.org/MarkUp/DTD/xhtml-role-qname-1.mod"

     ....................................................................... -->

<!-- XHTML Role Attribute Qname (Qualified Name) Module

     This module is contained in two parts, labeled Section 'A' and 'B':

       Section A declares parameter entities to support namespace-
       qualified names, namespace declarations, and name prefixing
       for XHTML Role and extensions.

       Section B declares parameter entities used to provide
       namespace-qualified names for the XHTML role attribute:

         %role.qname;   the xmlns-qualified name for @role

     XHTML Role extensions would create a module similar to this one.

<!-- Section A: XHTML Role Attribute XML Namespace Framework ::::::::::::::: -->

<!-- 1. Declare a %XHTML-ROLE.prefixed; conditional section keyword, used
        to activate namespace prefixing. The default value should
        inherit '%NS.prefixed;' from the DTD driver, so that unless
        overridden, the default behavior follows the overall DTD
        prefixing scheme.
<!ENTITY % NS.prefixed "IGNORE" >
<!ENTITY % XHTML-ROLE.prefixed "%NS.prefixed;" >

<!-- 2. Declare a parameter entity (eg., %XHTML-ROLE.xmlns;) containing
        the URI reference used to identify the XHTML Role Attribute namespace
<!ENTITY % XHTML-ROLE.xmlns  "http://www.w3.org/1999/xhtml" >

<!-- 3. Declare parameter entities (eg., %XML.prefix;) containing
        the default namespace prefix string(s) to use when prefixing
        is enabled. This may be overridden in the DTD driver or the
        internal subset of an document instance. If no default prefix
        is desired, this may be declared as an empty string.

     NOTE: As specified in [XMLNAMES], the namespace prefix serves
     as a proxy for the URI reference, and is not in itself significant.
<!ENTITY % XHTML-ROLE.prefix  "" >

<!-- 4. Declare parameter entities (eg., %XHTML-ROLE.pfx;) containing the
        colonized prefix(es) (eg., '%XHTML-ROLE.prefix;:') used when
        prefixing is active, an empty string when it is not.
<!ENTITY % XHTML-ROLE.pfx  "%XHTML-ROLE.prefix;:" >
<!ENTITY % XHTML-ROLE.pfx  "" >

<!-- declare qualified name extensions here ............ -->
<!ENTITY % xhtml-role-qname-extra.mod "" >

<!-- 5. The parameter entity %XHTML-ROLE.xmlns.extra.attrib; may be
        redeclared to contain any non-XHTML Role Attribute namespace 
        declaration attributes for namespaces embedded in XML. The default
        is an empty string.  XLink should be included here if used
        in the DTD.
<!ENTITY % XHTML-ROLE.xmlns.extra.attrib "" >

<!-- Section B: XML Qualified Names ::::::::::::::::::::::::::::: -->

<!-- 6. This section declares parameter entities used to provide
        namespace-qualified names for the XHTML role attribute.

<!ENTITY % xhtml-role.role.qname  "%XHTML-ROLE.pfx;role" >

<!-- The following defines a PE for use in the attribute sets of elements in
     other namespaces that want to incorporate the XHTML role attribute. Note
     that in this case the XHTML-ROLE.pfx should be defined. -->

<!ENTITY % xhtml-role.attrs.qname
   "%XHTML-ROLE.pfx;role             CDATA        #IMPLIED"

<!-- end of xhtml-role-qname-1.mod -->

A.2 Schema Implementation

The schema implementation of XHTML Role Attribute Module conforms to the requirements defined in [XHTML-MODULARIZATION11-2e]. It is included here as an example implementation.

A.2.1 Attributes Module

<?xml version="1.0" encoding="UTF-8"?>
    <xs:import namespace="http://www.w3.org/1999/xhtml/datatypes/" 
               schemaLocation="xhtml-datatypes-1.xsd" />

      This is the XML Schema attribute module for XHTML Role
      $Id: Overview.html,v 1.6 2018/10/09 13:22:04 denis Exp $
        <xs:documentation source="xhtml-copyright-1.xsd"/>
        <xs:documentation source="http://www.w3.org/TR/role-attribute#A_role"/>
    <xs:attribute name="role" type="xh11d:TERMorURIorCURIEs"/>

B. Acknowledgements

The following people contributed to the development of this document.

B.1 Participants in the PFWG at the time of publication

  1. David Bolter (Mozilla)
  2. Sally Cain (Royal National Institute of Blind People (RNIB))
  3. Alex Qiang Chen (University of Manchester)
  4. Charles Chen (Google, Inc.)
  5. Michael Cooper (W3C/MIT)
  6. James Craig (Apple, Inc.)
  7. Steve Faulkner (Invited Expert, The Paciello Group)
  8. Geoff Freed (Invited Expert, NCAM)
  9. Kentarou Fukuda (IBM)
  10. Georgios Grigoriadis (SAP AG)
  11. Jon Gunderson (Invited Expert, UIUC)
  12. Markus Gylling (DAISY Consortium)
  13. Sean Hayes (Microsoft Corporation)
  14. Kenny Johar (Microsoft Corporation)
  15. Shilpi Kapoor (BarrierBreak Technologies)
  16. Matthew King (IBM Corporation)
  17. Diego La Monica (International Webmasters Association / HTML Writers Guild (IWA-HWG))
  18. Rajesh Lal (Nokia Corporation)
  19. Gez Lemon (International Webmasters Association / HTML Writers Guild (IWA-HWG))
  20. Anders Markussen (Opera Software)
  21. Shane McCarron (Invited Expert, ApTest)
  22. Charles McCathieNevile (Opera Software)
  23. Mary Jo Mueller (IBM Corporation)
  24. James Nurthen (Oracle Corporation)
  25. Joshue O Connor (Invited Expert, NCBI Centre for Inclusive Technology)
  26. Sarah Pulis (Media Access Australia)
  27. T.V. Raman (Google, Inc.)
  28. Janina Sajka (Invited Expert, The Linux Foundation)
  29. Joseph Scheuhammer (Invited Expert, Inclusive Design Research Centre, OCAD University)
  30. Stefan Schnabel (SAP AG)
  31. Richard Schwerdtfeger (IBM Corporation)
  32. Lisa Seeman (Invited Expert)
  33. Cynthia Shelly (Microsoft Corporation)
  34. Andi Snow-Weaver (IBM Corporation)
  35. Gregg Vanderheiden (Invited Expert, Trace Research and Development Center)
  36. Léonie Watson (Nomensa)
  37. Gottfried Zimmermann (Invited Expert, Access Technologies Group)

B.2 Other previously active PFWG participants and contributors

Jim Allan (TSB), Simon Bates, Chris Blouch (AOL), Judy Brewer (W3C/MIT), Ben Caldwell (Trace), Charles Chen (Google, Inc.), Christian Cohrs, Dimitar Denev (Frauenhofer Gesellschaft), Donald Evans (AOL), Kentarou Fukuda (IBM Corporation), Becky Gibson (IBM), Alfred S. Gilman, Andres Gonzalez (Adobe Systems Inc.), Georgios Grigoriadis (SAP AG), Jeff Grimes (Oracle), Barbara Hartel, John Hrvatin (Microsoft Corporation), Masahiko Kaneko (Microsoft Corporation), Earl Johnson (Sun), Jael Kurz, Diego La Monica (International Webmasters Association / HTML Writers Guild (IWA-HWG)), Aaron Leventhal (IBM Corporation), Alex Li (SAP), Linda Mao (Microsoft), Anders Markussen (Opera Software), Matthew May (Adobe Systems Inc.), Lisa Pappas (Society for Technical Communication (STC)), Dave Pawson (RNIB), David Poehlman, Simon Pieters (Opera Software), T.V. Raman (Google, Inc.), Tony Ross (Microsoft Corporation), Martin Schaus (SAP AG), Marc Silbey (Microsoft Corporation), Henri Sivonen (Mozilla), Henny Swan (Opera Software), Vitaly Sourikov, Mike Squillace (IBM), Ryan Williams (Oracle), Tom Wlodkowski.

B.3 Enabling funders

This publication has been funded in part with Federal funds from the U.S. Department of Education, National Institute on Disability and Rehabilitation Research (NIDRR) 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.

C. References

C.1 Normative references

Shane McCarron; et al. RDFa Core 1.1: Syntax and processing rules for embedding RDF through attributes. 7 June 2012. W3C Recommendation. URL: http://www.w3.org/TR/2012/REC-rdfa-core-20120607/
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
Shane McCarron. XHTML™ Modularization 1.1 Second Edition. 29 July 2010. W3C Recommendation. URL: http://www.w3.org/TR/2010/REC-xhtml-modularization-20100729
XHTML 2 Working Group. XHTML Vocabulary. URL: http://www.w3.org/1999/xhtml/vocab
C. M. Sperberg-McQueen; et al. Extensible Markup Language (XML) 1.0 (Fifth Edition). 26 November 2008. W3C Recommendation. URL: http://www.w3.org/TR/2008/REC-xml-20081126/

C.2 Informative references

Ian Hickson; David Hyatt. HTML5. 29 March 2012. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/html5
Lisa Pappas; et al. Accessible Rich Internet Applications (WAI-ARIA) 1.0. 24 February 2009. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2009/WD-wai-aria-20090224
Andrew Layman; et al. Namespaces in XML 1.1 (Second Edition). 16 August 2006. W3C Recommendation. URL: http://www.w3.org/TR/2006/REC-xml-names11-20060816