Personalization Semantics Explainer 1.0

W3C Working Draft

This version:
Latest published version:
Latest editor's draft:
Previous version:
Richard Schwerdtfeger (Knowbility) (Editor until October 2017)


Personalization involves tailoring aspects of the user experience to meet the needs and preferences of the individual user. For example, having familiar terms and symbols is key to many users being able to use the web. However, what is familiar for one user may not be familiar to another, requiring them to learn new symbols. The challenge has been the ability to identify the types of content in a document that should be adapted to the preferred user experience. The introduction of standardized semantics allows web applications to customize the presentation of that content to one that is familiar to individuals based on their specific needs and preferences. This specification defines standard semantics to enable user driven personalization. For example, the association of user-preferred symbols with elements having those semantics. This ensures that users can quickly find familiar icons, for example, a help icon, within the context of user interface elements.

This document is an explanation for understanding how to use Personalization properties to personalize an accessible web site.

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

This document was published by the Accessible Platform Architectures Working Group as a Working Draft.

This is a Working Draft of Personalization Semantics Explainer 1.0 by the Accessible Platform Architectures Working Group. This specification changes from the previous version to introduce personalization semantics modules. This explainer introduces standard semantics to enable user-driven personalization, such as the association of a user-preferred symbols to elements having those semantics. The modules define features for specific categories of personalization, including Adaptable Content, Adaptable Help and Support and Adaptable Tools. This version has accepted the name and values of three attributes for the Content module: data-action, data-destination and data-purpose. Other properties in the vocabulary are not yet mature enough to suggest using them in production HTML with data- attributes.

To comment, file an issue in the W3C personalization semantics GitHub repository. If this is not feasible, send email to (archives). Comments are requested by 15 August 2019. In-progress updates to the document may be viewed in the publicly visible editors' draft.

Publication as a Working Draft 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 W3C Patent Policy. The group does not expect this document to become a W3C Recommendation. 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 1 March 2019 W3C Process Document.

1. Introduction

This section is non-normative.

The goals of this specification include:

This is a proposal for defining syntax for adaptable content such as: links, buttons, symbols, help and keyboard. This may be a WAI-ARIA COGA Extension, however implementation methods are currently being explored.

Technology holds the promise of being extremely flexible and the design of many systems includes the expectation that users will be able to optimize their interaction experience according to their personal preferences or accessibility needs.

1.1 Why We Need Personalization

We need personalization because:

Some users need extra support. This can include:

To achieve this we need standardized terms and supportive syntax. These can be linked to associated symbols, terms, translations and explanations. They are then provided to an individual based on personal preferences.

For example, assume an author can make it programmatically known that a button sends an email. Based on user preferences, the button renders with a symbol, term, and/or tooltips that are understandable by this particular user. It could automatically include F1 help that explains the send function in simple terms. It could be identified with a keyboard short cut that is always used for send. In addition, the button could be identified as important and always rendered, or always rendered very large.

Working examples of how this could be used in practice, with user preferences, are available on the task force implementations page.

Another use-case we would like to see is interoperable symbol set codes for non-verbal people. Products for people who are non-vocal often use symbols to help users communicate. These symbols are in fact an individual's language. Unfortunately many of these symbols are both subject to copyright and are not interoperable. That means end-users can only use one device, and can not use applications or assistive technologies from a different company. An open set of references for symbol codes for these symbol sets however, could be interoperable. That means the end user could use an open source symbol set or buy the symbols and use them across different devices or applications. Symbols could still be proprietary but they would also be interoperable.

1.2 Use Cases

Requirements for Personalization Semantics [personalization-semantics-requirements] elaborates many use cases that further contextualize the above summary of user needs. These use cases form the basis of requirements for this technology.

2. Modules

This specification has been divided into modules.

Each module has use cases and vocabularies:

3. Vocabulary Structure

Personalization Semantics is made of a vocabulary of properties and their values. This generic structure makes it possible to apply Personalization Semantics in a variety of contexts by adapting how the vocabulary is instantiated. The Vocabulary Implementations section below describes current ways to use the vocabulary.

3.1 Properties

Properties are the main units of personalization types supported by the vocabulary. A given property supports a specific type of personalization. That property would only be used once on a given piece of content, but multiple different properties could be used on the same piece of content to address different needs.

3.2 Values

Values provide the specific personalization information for the property. The possible values for each property are elabrated in the definition of the property in the modules. Some properties require the value to come from a predefined list of possible values, others can accept arbitrary strings, and some may accept multiple values. The value may be one of the following types:

Value representing either true or false, with a default "false" value.
Value representing true or false, with a default "undefined" value indicating the state or property is not relevant.
ID reference
Reference to the ID of another element in the same document
ID reference list
A list of one or more ID references.
A numerical value without a fractional component.
Any real numerical value.
Unconstrained value type.
One of a limited set of allowed values.
token list
A list of one or more tokens.
A Uniform Resource Identifier as defined by RFC 3986 [RFC3986]. It may reference a separate document, or a content fragment identifier in a separate document, or a content fragment identifier within the same document.

4. Vocabulary Implementations

At the present stage of development, the Personalization Semantics vocabulary can be used in HTML content using data- attributes [html5]. Attributes in this form can be used in valid HTML to implement features recognized by browser extensions or other special processors. Personalization Semantics is using this approach to gain early implementation experience of the features in a way that is simple and likely to be accepted within the web ecosystem as an interim approach.

For this publication of Personalization Semantics, the task force has accepted the name and values of three attributes for the Content module:

Other properties in the vocabulary are not yet mature enough to suggest using them in production HTML with data- attributes. Examples of those properties in the modules are to facilitate review, not to suggest implementation. See the discussion Prototypes with data dash.


The HTML data- attribute syntax is not intended to be used for long-term wide-scale features. The task force is using this approach at the moment to gain implementation experience and demonstrate the usefulness of Personalization Semantics in practice. Content authors and user agent implementers should be aware that the recommended approach to use the vocabulary is expected to change, and structure their implementation in a manner that will facilitate the transition to a new syntax.

A. Change Log

This section is non-normative.

The full commit history to personalization semantics is available.

A.1 Significant editorial changes since the First Public Working Draft

B. Acknowledgments

This section is non-normative.

The following people contributed to the development of this document.

B.1 Participants active in the Personalization TF at the time of publication

B.2 Other Personalization TF contributors, commenters, and previously active participants

B.3 Enabling funders

This publication has been funded in part with U.S. Federal funds from the Health and Human Services, National Institute on Disability, Independent Living, and Rehabilitation Research (NIDILRR) under contract number HHSP23301500054C. The content of this publication does not necessarily reflect the views or policies of the U.S. Department of Health and Human Services, nor does mention of trade names, commercial products, or organizations imply endorsement by the U.S. Government.

C. References

C.1 Informative references

HTML5. Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. W3C. 27 March 2018. W3C Recommendation. URL:
Requirements for Personalization Semantics. W3C. URL:
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: