Repository navigation
Interop with/use of accessibilityFeature property for MathML #539
Description
I was investigating the question of whether there is a standardized way to annotate the target consumer for a given MathML dialect, mostly thinking of assistive technology.
(short answer: There isn't)
Instead, I discovered that ePub 3 has put in some work to leverage schema.org vocabularies for annotating various features that may or may not be enabled in a given document.
Most relevant may be the accessibilityFeature property, ands its schema.org accessibilityFeature vocabulary.
That effort seems to have independently (or has there been contact?) invented an annotation for chemical formulas, called MathML-chemistry.
The great enabling feature of using this approach is that we can do global, document-level, annotations, which we are currently missing. And it is helpful that it documents a fixed vocabulary for feature flags.
Reading their current vocabulary, this would be an example that the MathML on a page is already remediated for accessibility, either via alttext "or other means" and pertains to chemistry:
<article vocab="https://schema.org/" typeof="DigitalDocument">
<meta property="accessibilityFeature" content="describedMath"/>
<meta property="accessibilityFeature" content="MathML"/>
<meta property="accessibilityFeature" content="MathML-chemistry"/>
<!-- ... -->Suggestion: I think the WG should discuss the mechanism and its possible use in MathML 4, and if seen favorably -- suggest helpful extensions.
Activity
dginev commentedon Aug 2, 2025
Separately, and closer to my original query about specifying target consumers, there is a property that designates supported vendor APIs.
Namely, the accessibilityAPI property.
For example, this markup would indicate compatibility with the Android Access API:
davidcarlisle commentedon Aug 2, 2025
but the description of that property says
so it's probably not ideal for describing whether a html+mathml document will work with any specific API. (That doesn't mean there is anything that is better)
NSoiffer commentedon Aug 3, 2025
I think there a some subtleties with the accessibilityAPI property that I don't understand. It is described as indicating " that assistive technologies on the platform should be able to access the resource." But (for example) MSAA and UIA are both Windows technologies, so if "platform" means OS, then why have two? But I think this is not about saying this document works this (random) technology, but that this document works with this platform-specific accessibility API.
The accessibilityFeature property (as are all the features?) a way for consumers to know whether content has the level/features they are interested in. As their example says, with it, a user can known when they get a higher level of accessibility because is uses MathML for the math (and/or the chemistry) or whether they are stuck with descriptions or some specialized format that requires specialized tools to read.
Although those two fields don't seem appropriate, perhaps we should start a conversation with some of the EPUB folks to see if there is something more appropriate, and if not, get it added. @clapierre is a member of that community, so maybe he can elaborate.
dginev commentedon Aug 4, 2025
@clapierre We are exploring possible approaches to globally announce the features from MathML 4 Intent which are required by/present in an HTML5 document.
That should be completely compatible with the schema.org approach, and at least for now I don't quite understand the subtle issues others have identified with the
accessibilityAPIandaccessibilityFeatureproperties. One practical way forward would be to come up with a proposal for a handful of useful additions to their schema.org vocabularies and consult with the ePub group.clapierre commentedon Aug 13, 2025
Hi all, my apologies for the delay in responding, as I was out last week and just caught up on this thread.
For reference, here is some information regarding the Core Accessibility API Mappings 1.2.
In EPUB, we have deprecated the use of
accessibilityAPIandaccessibilityControls. These properties are defined at the Reading System level, not the content level (which is the digital EPUB book itself). As @NSoiffer said, this is at the OS/Platform level, so I don't believe you need to be concerned with it for your purposes.What @dginev is suggesting is exactly what was intended when we first asked Schema.org for the new
accessibilityFeatureproperty. This property was designed to be used not only for EPUB books but for any content or HTML page.We have an active W3C Community Group, "Accessibility Discoverability Vocabulary for Schema.org Community Group," where we are working on the latest editors' draft. In the current "Schema.org Accessibility Properties for Discoverability Vocabulary" document, you'll see under "4.2.4 Specialized markup terms" that both
MathMLandMathML-chemistryare included, along withlatexandlatex-chemistry.The presence of these values under
accessibilityFeaturesimply means that content of that type exists in the document or on the page. We don't get into whether it can be rendered or accessed; the property's primary purpose is to allow for "search and discovery" of this content.If there are other values you feel should be included, such as more prescriptive terms like
MathML-chemicalEquationorMathML-chemicalMolecule, or some other type of common math content, please feel free to file a GitHub issue with your request on our a11y-discov-vocab repository.Thanks
Charles
NSoiffer commentedon Aug 14, 2025
@clapierre: thanks for the response. Good to know that I wasn't making up what it is used for :-)
polx commentedon Sep 4, 2025
This would be good if we could point to some dictionary of properties and/or default intents...