Schema.org Accessibility Properties for Discoverability Vocabulary

Final Community Group Report

Latest published version:
https://www.w3.org/2021/a11y-discov-vocab/latest/
Latest editor's draft:
https://w3c.github.io/a11y-discov-vocab/
Editors:
Charles LaPierre (Benetech)
Madeleine Rothberg (WGBH)
Matt Garrish (DAISY Consortium)

Abstract

This document defines the recommended vocabularies for use with the Schema.org accessibility properties for discoverability of creative works.

Status of This Document

This specification was published by the Accessibility Discoverability Vocabulary for Schema.org Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Final Specification Agreement (FSA) other conditions apply. Learn more about W3C Community and Business Groups.

GitHub Issues are preferred for discussion of this specification.

1. Introduction

1.1 Background

The CreativeWork type [schema-org] includes the following accessibility properties for discoverability:

Although schema.org contains many other properties that describe the accessibility of objects in its taxonomy, these specific properties were developed together as part of a project to improve the discoverability of accessible resources headed by Benetech and IMS Global. Many of these properties were derived directly from the Global Access for All (AfA) Information Model Data Element Specification.

Part of this work included defining vocabularies of recommended values for use with these properties to ensure predictability for machine processing. This document represents those vocabularies.

By defining these vocabularies, not only is it simpler for authors to understand and apply the properties, but it ensures that search tools, user agents and other machine intelligence can easily parse and inform users of the information.

Note

For more information about the original project, refer to the Accessibility Metadata Project's web site.

Note

For more information on how to use schema.org accessibility properties not covered by this vocabulary, please refer to their relevant definitions in schema.org.

1.2 Vocabulary Naming Convention

The values defined in this vocabulary follow a camel casing convention: single words are lowercase, while compound words are concatenated into a single value with a capital letter indicating the start of each connected word (e.g., "alternativeText"). This convention is not applied to acronyms, accessibility APIs, and other values that already have recognized naming conventions (e.g., "MathML" and "iOSAccessibility").

To ensure maximum interoperability with user agents that process these properties, use the values exactly as they are defined in this vocabulary. Alternative case spellings may not be recognized (e.g., "mathml" or "aria").

User agent developers should be aware that these values may not be strictly validated depending on the context in which they are created and used. Two values that differ only in case should be treated as identical.

1.3 Extending Vocabulary Terms

This vocabulary currently uses the old slash extension syntax employed by Schema.org until 2015. In this model, extensions of a term are made by adding a slash followed by a refinement term. For example, see the braille feature for specifying specific braille codes.

Authors are advised to use this extension mechanism sparingly at this time, as a future version of the vocabulary may update this approach.

2. The accessibilityAPI Property

2.1 Application

Indicates that the resource is compatible with the referenced accessibility API.

Compatibility with an accessibility API indicates that assistive technologies on the platform should be able to access the resource.

The property is not applicable to resources that are not tightly integrated with their user interface. It can describe whether a word processing document that only opens in a specific application will work on a given platform, for example, but is not a useful indicator of whether an HTML document will, as there are numerous user agents a user could use to render it.

Setting the property means that the resource is compatible with the given API(s). It does not necessarily mean that the content will be fully accessible to any given user group.

2.2 Vocabulary

2.2.1 AndroidAccessibility

Indicates the resource is compatible with the Android Accessibility API.

2.2.2 ARIA

Indicates the resource uses ARIA markup to improve interoperability with platform APIs.

2.2.3 ATK

Indicates the resource is compatible with the Accessibility Toolkit (ATK) API for GNOME.

2.2.4 AT-SPI

Indicates the resource is compatible with the Assistive Technology Service Provider Interface (AT-SPI) API for GNOME.

2.2.5 BlackberryAccessibility

Indicates the resource is compatible with the Blackberry Accessibility API.

2.2.6 iAccessible2

Indicates the resource is compatible with the iAccessible2 API for Windows.

2.2.7 iOSAccessibility

Indicates the resource is compatible with the iAccessible2 API for Apple iOS devices.

2.2.8 JavaAccessibility

Indicates the resource is compatible with the Java Accessibility API (JAAPI).

2.2.9 MacOSXAccessibility

Indicates the resource is compatible with the iAccessible2 API for Windows.

2.2.10 MSAA

Indicates the resource is compatible with the Microsoft Active Accessibility (MSAA) API for Windows.

2.2.11 UIAutomation

Indicates the resource is compatible with the User Interface Automation API for Windows.

3. The accessibilityControl Property

3.1 Application

Identifies one or more input methods that allow access to all of the application functionality.

The accessibilityControl property is used to describe the ability of users to interact with the user interface controls that applications provide.

The property is not applicable to resources that are not tightly integrated with their user interface. It can describe whether users can control a word processing document that only opens in a specific application, for example, but is not a useful indicator of whether users can control an HTML document, as there are numerous user agent and assistive technology pairings a user could use to access it.

Setting the property means that the specified control method(s) are compatible with the resource.

3.2 Vocabulary

3.2.1 fullKeyboardControl

Users can fully control the resource through keyboard input.

3.2.2 fullMouseControl

Users can fully control the resource through mouse input.

3.2.3 fullSwitchControl

Users can fully control the resource through switch input.

3.2.4 fullTouchControl

Users can fully control the resource through touch input.

3.2.5 fullVideoControl

Users can fully control the resource through video input.

3.2.6 fullVoiceControl

Users can fully control the resource through voice input.

4. The accessibilityFeature Property

4.1 Application

Content features of the resource, such as accessible media, alternatives and supported enhancements for accessibility.

The accessibilityFeature property provides a list of all the applicable accessibility characteristics of the content. It allows a user agent to discover these characteristics without having to parse or interpret the structure of the content.

For ease of reading, this section splits the vocabulary into four distinct groups:

The vocabulary also includes the term "none" that authors can set to indicate that the resource does not contain special enhancements. This value avoids the ambiguity that can arise if a resource has not been checked.

4.2 Vocabulary

4.2.1 Transformation Terms

Transformation features either state how content is available in a transformed state or is set up so that a user can transform it. These properties derive from WCAG 2 Success Criterion 1.4.

4.2.1.1 highContrastAudio

Audio content with speech in the foreground meets the contrast thresholds set out in WCAG Success Criteria 1.4.7. The requirement the audio meets can be appended, but is not required:

  • /noBackground - no background noise is present
  • /reducedBackground - at least 20db difference between foreground speech and background noise
  • /switchableBackground - background noise can be turned off (sufficient contrast may not be met without doing so)
4.2.1.2 highContrastDisplay

Content meets the visual contrast threshold set out in WCAG Success Criteria 1.4.6.

4.2.1.3 largePrint

The content has been formatted to meet large print guidelines. The specific point size may optionally be added as an extension (e.g., largePrint/18).

The property is not set if the font size can be increased. See displayTransformability.

4.2.1.4 displayTransformability

Display properties are controllable by the user. This property can be set, for example, if custom CSS style sheets can be applied to the content to control the appearance. It can also be used to indicate that styling in document formats like Word and PDF can be modified.

This property can be modified to identify the specific display properties that allow meaningful control. Modifiers should take the form of CSS property names, even if CSS is not the document styling format:

  • /font-size
  • /font-family
  • /line-height
  • /word-spacing
  • /color
  • /background-color

Note that many CSS display properties can be modified, but not all usefully enhance the accessibility (e.g., image-based content).

4.2.2 Structure and Navigation Terms

The following values identify key navigation aids available with the work.

4.2.2.1 annotations

The work includes annotations from the author, instructor and/or others.

4.2.2.2 bookmarks

The work includes bookmarks to facilitate navigation to key points.

4.2.2.3 index

The work includes an index to the content.

4.2.2.4 printPageNumbers

The work includes equivalent print page numbers. This setting is most commonly used with ebooks for which there is a print equivalent.

4.2.2.5 readingOrder

The reading order of the content is clearly defined in the markup (e.g., figures, sidebars and other secondary content has been marked up to allow it to be skipped automatically and/or manually escaped from.

4.2.2.6 structuralNavigation

The use of headings in the work fully and accurately reflects the document hierarchy, allowing navigation by assistive technologies.

4.2.2.7 taggedPDF

The structures in a PDF have been tagged to improve the navigation of the content.

4.2.3 Content Control Terms

The following values identify aspects of the content that users can control to improve access to the content. Do not confuse these control features with the accessibilityControl property, which defines input methods used to control the content.

4.2.3.1 synchronizedAudioText

Describes a resource that offers both audio and text, with information that allows them to be rendered simultaneously. The granularity of the synchronization is not specified. This term is not recommended when the only material that is synchronized is the document headings.

4.2.3.2 timingControl

For content with timed interaction, this value indicates that the user can control the timing to meet their needs (e.g., pause and reset)

4.2.3.3 unlocked

No digital rights management or other content restriction protocols have been applied to the resource.

4.2.4 Augmentation Terms

Augmentation is the provision of intellectual content in a different access mode from its source.

4.2.4.1 alternativeText

Alternative text is provided for visual content (e.g., via the [HTML] alt attribute).

4.2.4.2 audioDescription

Audio descriptions are available (e.g., via an [HTML] track element with its kind attribute set to "descriptions").

4.2.4.3 braille

The content is in braille format, or alternatives are available in braille. This value can be extended to identify the different types of braille (/ASCII, /unicode, /music, /math, /chemistry or /nemeth), and whether the braille is contracted or not (/grade1 and /grade2). Other extensions such as the code the braille conforms to can also be specified.

4.2.4.4 captions

Indicates that synchronized captions are available for audio and video content.

4.2.4.5 ChemML

Identifies that chemical information is encoded using the ChemML markup language.

4.2.4.6 describedMath

Textual descriptions of math equations are included, whether in the alt attribute for image-based equations, using the alttext attribute for [MathML] equations, or by other means.

4.2.4.7 latex

Identifies that mathematical equations and formulas are encoded in the LaTeX typesetting system.

4.2.4.8 longDescription

Descriptions are provided for image-based visual content and/or complex structures such as tables, mathematics, diagrams, and charts.

4.2.4.9 MathML

Identifies that mathematical equations and formulas are encoded in [MathML].

4.2.4.10 rubyAnnotations

Indicates that ruby annotations [HTML] are provided in the content. Ruby annotations are used as pronunciation guides for the logographic characters for languages like Chinese or Japanese. It makes difficult Kanji or CJK ideographic characters more accessible.

The absence of rubyAnnotations implies that no CJK ideographic characters have ruby.

4.2.4.11 signLanguage

Synchronized sign language interpretation is available for audio and video content. The value may be extended by adding an [ISO-639] sign language code. For example, /sgn-en-us for American Sign Language.

4.2.4.12 tactileGraphic

Tactile graphics are provided. For example, as described in the BANA Guidelines and Standards for Tactile Graphics.

4.2.4.13 tactileObject

The content is a tactile 3D object, or the model to generate one is included.

4.2.4.14 transcript

Indicates that a transcript of the audio content is available.

4.2.4.15 ttsMarkup

One or more of [SSML], [Pronunciation-Lexicon], and [CSS3-Speech] properties has been used to enhance text-to-speech playback quality.

4.2.5 none

Indicates that the resource does not contain any accessibility features.

5. The accessibilityHazard Property

5.1 Application

A characteristic of the described resource that is physiologically dangerous to some users. Related to WCAG 2.0 guideline 2.3.

Identifying potential hazards that a resource poses allows users to determine if a resource poses a risk to them and to potentially filter out content that could be harmful.

If no hazards are known to exist, it is recommended to use the value "none". If the content has hazard(s), include positive assertions for the hazards it has and negative assertions (the values that begin with "no") for the others.

If this property is not set for a resource, it is not possible to state whether it presents hazards or not. Similarly, if an author sets the value unknown, they are stating that they do not know whether hazards are present (e.g., because they do not know how, or are unable, to assess them).

5.2 Vocabulary

5.2.1 flashing

Indicates that the resource presents a flashing hazard for photosensitive persons.

This value should be set when the content meets the hazard thresholds described in Success Criterion 2.3.1 Three Flashes or Below Threshold [WCAG2].

5.2.2 noFlashingHazard

Indicates that the resource does not present a flashing hazard.

This value should be set when the content conforms to Success Criterion 2.3.1 Three Flashes or Below Threshold [WCAG2].

5.2.3 motionSimulation

Indicates that the resource contains instances of motion simulation that may affect some individuals.

Some examples of motion simulation include video games with a first-person perspective and CSS-controlled backgrounds that move when a user scrolls a page.

5.2.4 noMotionSimulationHazard

Indicates that the resource does not contain instances of motion simulation.

5.2.5 sound

Indicates that the resource contains auditory sounds that may affect some individuals.

Editor's note

The application of this value is currently under discussion as its application is underspecified.

5.2.6 noSoundHazard

Indicates that the resource does not contain auditory hazards.

Editor's note

The application of this value is currently under discussion as its application is underspecified.

5.2.7 unknown

Indicates that the author is not able to determine if the resource presents any hazards.

5.2.8 none

Indicates that the resource does not contain any hazards.

6. The accessibilitySummary Property

A human-readable summary of specific accessibility features or deficiencies, consistent with the other accessibility metadata but expressing subtleties such as "short descriptions are present but long descriptions will be needed for non-visual users" or "short descriptions are present and no long descriptions are needed."

The accessibilitySummary property is a free-form field that allows authors to describe the accessible properties of the resource. As a result, it does not have an associated vocabulary.

7. The accessMode Property

7.1 Application

The human sensory perceptual system or cognitive faculty through which a person may process or perceive information.

The accessMode property describes the ways information is encoded in the resource, but it does not tell users if all the specified modes are necessary to consume the information or if only individual modes or combinations are necessary (e.g., in a book with audio content, the ability to read textual content may only be necessary if transcripts are provided).

The accessModeSufficient property is designed to fill this gap of understanding the combinations of modes necessary to fully consume the information.

7.2 Vocabulary

7.2.1 auditory

Indicates that the resource contains information encoded in auditory form.

7.2.2 chartOnVisual

Indicates that the resource contains charts encoded in visual form.

7.2.3 chemOnVisual

Indicates that the resource contains chemical equations encoded in visual form.

7.2.4 colorDependent

Indicates that the resource contains information encoded in such that color perception is necessary.

7.2.5 diagramOnVisual

Indicates that the resource contains diagrams encoded in visual form.

7.2.6 mathOnVisual

Indicates that the resource contains mathematical notations encoded in visual form.

7.2.7 musicOnVisual

Indicates that the resource contains musical notation encoded in visual form.

7.2.8 tactile

Indicates that the resource contains information encoded in tactile form.

Note that although an indication of a tactile mode often indicates the content is encoded using a braille system, this is not always the case. Tactile perception may also indicate, for example, the use of tactile graphics to convey information.

7.2.9 textOnVisual

Indicates that the resource contains text encoded in visual form.

7.2.10 textual

Indicates that the resource contains information encoded in textual form.

7.2.11 visual

Indicates that the resource contains information encoded in visual form.

8. The accessModeSufficient property

8.1 Application

A list of single or combined accessModes that are sufficient to understand all the intellectual content of a resource.

Although the access modes indicate how the information is encoded in its default form, knowing the encoding only describes one possible perceptual pathway through the content. For example, a book with textual and visual content will at least require an individual who can read text and view images.

The author of the content may provide alternatives to a specific access mode that allow the content to be consumed in an alternative manner. The use of alternative text and extended descriptions, for example, can allow a user who cannot perceive visual content to read all the information in textual form.

The list(s) of sufficient access modes provides users with the possible combinations of reading modes that allow the content to be read in full.

8.2 Vocabulary

8.2.1 auditory

Indicates that auditory perception is necessary to consume the information.

8.2.2 tactile

Indicates that tactile perception is necessary to consume the information.

8.2.3 textual

Indicates that the ability to read textual content is necessary to consume the information.

Note that reading textual content does not require visual perception, as textual content can be rendered as audio using a text-to-speech capable device or assistive technology.

8.2.4 visual

Indicates that visual perception is necessary to consume the information.

9. Examples

9.1 Book

The following example shows how the accessibility metadata is used to enhance Bookshare records. A description of the process of adding this metadata, and a corpus of searchable books, can be found at the accessibility metadata website.

<div itemscope="" itemtype="http://schema.org/Book">
   <meta itemprop="bookFormat" content="EBook/DAISY3" />
   <meta itemprop="accessibilityFeature" content="largePrint" />
   <meta itemprop="accessibilityFeature" content="highContrastDisplay" />
   <meta itemprop="accessibilityFeature" content="displayTransformability/resizeText" />
   <meta itemprop="accessibilityFeature" content="longDescription" />
   <meta itemprop="accessibilityFeature" content="alternativeText" />
   <meta itemprop="accessibilityFeature" content="readingOrder" />
   <meta itemprop="accessibilityFeature" content="structuralNavigation" />
   <meta itemprop="accessibilityFeature" content="tableOfContents" />
   <meta itemprop="accessibilityControl" content="fullKeyboardControl" />
   <meta itemprop="accessibilityControl" content="fullMouseControl" />
   <meta itemprop="accessibilityHazard" content="noFlashingHazard" />
   <meta itemprop="accessibilityHazard" content="noMotionSimulationHazard" />
   <meta itemprop="accessibilityHazard" content="noSoundHazard" />
   <meta itemprop="accessibilityAPI" content="ARIA" />
   <dl>
      <dt>Name:</dt>
      <dd itemprop="name">Holt Physical Science</dd>
      <dt>Brief Synopsis:</dt>
      <dd itemprop="description">NIMAC-sourced textbook</dd>
      <dt>Long Synopsis:</dt>
      <dd>N/A</dd>
      <dt>Book Quality:</dt>
      <dd>Publisher Quality</dd>
      <dt>Book Size:</dt>
      <dd itemprop="numberOfPages">598 Pages</dd>
      <dt>ISBN-13:</dt>
      <dd itemprop="isbn">9780030426599</dd>
      <dt>Publisher:</dt>
      <dd itemprop="publisher" itemtype="http://schema.org/Organization" itemscope="">Holt, Rinehart
         and Winston</dd>
      <dt>Date of Addition:</dt>
      <dd>06/08/10</dd>
      <dt>Copyright Date:</dt>
      <dd itemprop="copyrightYear">2007</dd>
      <dt>Copyrighted By:</dt>
      <dd itemprop="copyrightHolder" itemtype="http://schema.org/Organization" itemscope="">Holt,
         Rinehart and Winston</dd>
      <dt>Adult content:</dt>
      <dd><meta itemprop="isFamilyFriendly" content="true" />No</dd>
      <dt>Language:</dt>
      <dd><meta itemprop="inLanguage" content="en-US" />English US</dd>
      <dt>Essential Images:</dt>
      <dd>861</dd>
      <dt>Described Images:</dt>
      <dd>910</dd>
      <dt>Categories:</dt>
      <dd><span itemprop="genre">Educational Materials</span></dd>
      <dt>Grade Levels:</dt>
      <dd>Sixth grade, Seventh grade, Eighth grade</dd>
      <dt>Submitted By:</dt>
      <dd>Bookshare Staff</dd>
      <dt>NIMAC:</dt>
      <dd>This book is currently only available to public K-12 schools and organizations in the United
         States for use with students with an IEP, because it was created from files supplied by the
         NIMAC under these restrictions. Learn more in the NIMAC Support Center.</dd>
   </dl>
   
   <div class="bookReviews" itemprop="aggregateRating" itemscope=""
      itemtype="http://schema.org/AggregateRating">
      <h2>Reviews of Holt Physical Science (<span itemprop="reviewCount">0</span> reviews)</h2>
      <div class="bookReviewScore">
         <span><span itemprop="ratingValue">0</span> - No Rating Yet</span>
      </div>
   </div>
</div>

(The source record can be found at https://www.bookshare.org/browse/book/190639.)

9.2 Video

This example shows how the accessibility metadata can be used to augment a record for a video.

<dl itemtype="http://schema.org/VideoObject" itemscope="">
   <dt>Title:</dt>
   <dd itemprop="name">Arctic Climate Perspectives</dd>
   <dt>Description:</dt>
   <dd itemprop="description">This video, adapted from material provided by the ECHO partners,
      describes how global climate change is affecting Barrow, Alaska.</dd>
   <dt>Adaptation Type:</dt>
   <dd><span itemprop="accessibilityFeature">captions</span></dd>
   <dt>Access Mode:</dt>
   <dd>auditory, visual</dd>
   <dt>URL:</dt>
   <dd><a itemprop="url" href="http://www.teachersdomain.org/asset/echo07_vid_climate"
      >http://www.teachersdomain.org/asset/echo07_vid_climate</a>/</dd>
   <dt>Has Adaptation:</dt>
   <dd>http://www.teachersdomain.org/asset/echo07_vid_climate_dvs/</dd>
   <dt>Subjects:</dt>
   <dd><span itemprop="about">National K-12 Subject::Science::Earth and Space Science::Water Cycle,
      Weather, and Climate::Structure and Composition of the Atmosphere, National K-12
      Subject::Science::Earth and Space Science::Water Cycle, Weather, and
      Climate::Climate</span></dd>
   <dt>Education Level:</dt>
   <dd>Grade 6, Grade 7, Grade 8, Grade 9</dd>
   <dt>Audience:</dt>
   <dd><span itemprop="intendedEndUserRole">Learner</span></dd>
   <dt>Resource Type:</dt>
   <dd><span itemprop="genre">Audio/Visual</span>, <span itemprop="genre">Movie/Animation</span></dd>
   <dt>Language:</dt>
   <dd><span itemprop="inLanguage">en-US</span></dd>
   <dt>Publication Date:</dt>
   <dd itemprop="datePublished">2007-02-12</dd>
   <dt>Rights:</dt>
   <dd>Download and Share, <a itemprop="useRightsUrl"
      href="http://www.teachersdomain.org/oerlicense/2/"
      >http://www.teachersdomain.org/oerlicense/2/</a></dd>
</dl>

A. Change Log

Note that this change log only identifies substantive changes to the vocabulary — those that add or deprecate terms, or are similarly noteworthy.

For a list of all issues addressed (typos, minor definition modifications, etc.), refer to the Community Group's issue tracker.

B. Acknowledgments

The editors would like to thank the Accessibility Discoverability Vocabulary for Schema.org Community Group participants for their ongoing input and suggestions to improve this vocabulary.

Additional thanks goes to the original participants of the Accessibility Metadata Project for their work bringing the properties and vocabularies to reality.

C. References

C.1 Informative references

[CSS3-Speech]
CSS Speech Module. Daniel Weck. W3C. 10 March 2020. W3C Candidate Recommendation. URL: https://www.w3.org/TR/css-speech-1/
[HTML]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[ISO-639]
Code for the representation of names of languages. ISO/TC 37/SC 2. ISO. 1988. International Standard. URL: https://www.iso.org/standard/4766.html
[MathML]
Mathematical Markup Language (MathML) 1.01 Specification. Patrick D F Ion; Robert R Miner. W3C. 7 July 1999. W3C Recommendation. URL: https://www.w3.org/TR/REC-MathML/
[Pronunciation-Lexicon]
Pronunciation Lexicon Specification (PLS) Version 1.0. Paolo Baggia. W3C. 14 October 2008. W3C Recommendation. URL: https://www.w3.org/TR/pronunciation-lexicon/
[schema-org]
Schema.org. W3C Schema.org Community Group. W3C. 6.0. URL: https://schema.org/
[SSML]
Speech Synthesis Markup Language (SSML) Version 1.1. Daniel Burnett; Zhi Wei Shuang. W3C. 7 September 2010. W3C Recommendation. URL: https://www.w3.org/TR/speech-synthesis11/
[WCAG2]
Web Content Accessibility Guidelines (WCAG) 2. W3C. URL: https://www.w3.org/TR/WCAG2/