[EPUB][A11y] schema:accessibilityAPI

[Romain]

Hi all,

I'd like to better understand the schema:accessibilityAPI metadata property.

The EPUB Accessibility spec [1] and the schema.org reference [2] say that the metadata "indicates that the resource is compatible with the referenced accessibility API". The WebSchemas wiki gives a list of possible values [3]. The EPUB Accessibility Techniques shows a couple examples [4].

I'm confused by a couple things:

- on the one hand, one of the possible value is "ARIA". However, ARIA is not really an API, so what is meant exactly by the presence of the property with the "ARIA" value? HTML content could be perfectly accessible without using ARIA; to which extent is it useful to know that ARIA is being used? Who's the intended audience for the property

- one the other hand, all the other values seem to describe platform accessibility APIs (MSAA, UAAutomation, iAccessble2, MacOSXAccessibility, etc). That the content is compatible with these primarily depends on the browsers exposing information in the accessibility tree, then on the native APIs exposing the information. As far as I know, the same content can be correctly exposed to UAAutomation when browsed with Edge, to MSAA and iAccessible2 with Firefox on Windows, to NSAccessibility via Safari or Firefox on OS X, etc. So what is meant by the property, and how is it intended to be used? Do we really expect Authors to evaluate that compatibility at the API level?
If this kind information is useful, then wouldn't we rather want to know which browser + AT combination is it compatible with? This seems to go pretty far.

Does anyone have more guidance or explanation on this property?

Best,
Romain.


[1] http://www.idpf.org/epub/a11y/accessibility.html#sec-disc-package
[2] https://schema.org/accessibilityAPI
[3] https://www.w3.org/wiki/WebSchemas/Accessibility
[4] http://www.idpf.org/epub/a11y/techniques/techniques.html#sec-meta-006

[Madeleine Rothberg]

Hi Romain,

Those are good questions. accessibilityAPI is mainly meant for cataloging software and apps, not for describing web pages (ARIA excepted). When downloading an app, users may want to know if the app developer used the relevant API for their platform. It might be used by intelligent search services to find the best apps for users who use assistive technology that relies on those frameworks.

ARIA is a bit of a special case. And as you noted it is entirely possible to write HTML that is accessible without using ARIA. These days, though, most complex web sites could use a dose of ARIA so knowing that the site author is aware of ARIA and claims to have used it could be good information.

As the current technique says, this is relevant to epub packages mainly if they include scripted interactive content which is essentially an application inside the EPUB book.

-Madeleine

>--
>You received this message because you are subscribed to the Google Groups "EPUB Working Group" group.
>To unsubscribe from this group and stop receiving emails from it, send an email to epub-working-gr...@googlegroups.com.
>For more options, visit https://groups.google.com/d/optout.

[Leonard Rosenthol]

But to Romain’s comment – how would the script’s author (or the EPUB author) be able to comment on whether their script complies with those APIs? It will not be making any of those API calls directly – only the UA/RS will be doing so…

Leonard

[Matt Garrish]

In the case of ARIA, while you might not be making the API calls directly from the content, you can test if your script correctly sets and maintains the ARIA roles, state and properties during the lifecycle of your interactive application. Ultimately it's the RS and AT that are communicating via one of the underlying platform APIs when these changes occur, but it's still useful information to the reader that if they have an ARIA-capable reading system then the content will be controllable.

Matt

[White, Jason J]

> -----Original Message-----
> From: epub-work...@googlegroups.com [mailto:epub-working-
> gr...@googlegroups.com] On Behalf Of Matt Garrish
>
> In the case of ARIA, while you might not be making the API calls directly from
> the content, you can test if your script correctly sets and maintains the ARIA
> roles, state and properties during the lifecycle of your interactive application.

[Jason] This is true, but in such a case it is sufficient to assert WAI-ARIA conformance in describing the relevant features of the application in the metadata.

I think it should be acknowledged that most of the values of the accessibilityAPI metadata property are not relevant to EPUB. However, schema.org has many use cases unrelated to EPUB, for example a Web site that offers applications for download, in which circumstances this property would be highly relevant, indeed useful. For example, if I'm looking for a particular kind of application, one that asserts accessibility API compatibility for my platform in its Web page's metadata could be ranked more highly in the results returned by a search engine.

An assertion of ARIA support is the only relevant use case that comes to mind in the EPUB context, however.


________________________________

This e-mail and any files transmitted with it may contain privileged or confidential information. It is solely for use by the individual for whom it is intended, even if addressed incorrectly. If you received this e-mail in error, please notify the sender; do not disclose, copy, distribute, or take any action in reliance on the contents of this information; and delete it from your system. Any other use of this e-mail is prohibited.


Thank you for your compliance.

________________________________

[Matt Garrish]

> it is sufficient to assert WAI-ARIA conformance in describing the relevant features of the application

Yes, but I think there's value in also being able to include some kind of statement at a higher level. Perhaps this could be done with a different descriptive feature? I can't think of a good name in the morning, but something like "Accessible Interactivity".

> An assertion of ARIA support is the only relevant use case that comes to mind in the EPUB context

I've struggled with this. I agree it's the most common, but it's hard to rule out other cases entirely. The specification is intended to cover all versions of EPUB, and Flash video was embeddable in some EPUB 2 reading systems. You might want to state that the content will only be accessible with certain platforms APIs in that case.

Matt

[White, Jason J]

> -----Original Message-----
> From: epub-work...@googlegroups.com [mailto:epub-working-

> Yes, but I think there's value in also being able to include some kind of statement
> at a higher level. Perhaps this could be done with a different descriptive feature?

[Jason] Perhaps a clearer conception of the use cases would help me to understand what you have in mind here.

> I can't think of a good name in the morning, but something like "Accessible
> Interactivity".

[Jason] What can an author include in a publication that would meet this description, apart from scripts and ARIA? Let's understand what it is before we decide how abstractly to describe it.

>
> > An assertion of ARIA support is the only relevant use case that comes
> > to mind in the EPUB context
>
> I've struggled with this. I agree it's the most common, but it's hard to rule out
> other cases entirely. The specification is intended to cover all versions of EPUB,
> and Flash video was embeddable in some EPUB 2 reading systems. You might
> want to state that the content will only be accessible with certain platforms APIs
> in that case.

[Jason] If it goes beyond Flash video to scripted Flash content (including video controls that are part of the player application) then the relevant Flash accessibility standards need to be followed - but we don't have a metadata value for those yet. To the best of my knowledge, they were only ever implemented on Microsoft platforms, were widely disregarded by Flash developers, and never earned a good reputation among accessibility specialists.

Is it possible to embed or refer to Java applets? Granted, they're seldom used these days.

On balance, I would retain the accessibilityAPI metadata property and note that ARIA is the main use case (but without removing the other values for EPUB purposes). The fact that the schema.org metadata properties are not EPUB-specific, but intended for much wider use on the Web, justifies the full range of values even if most of them aren't likely to be used in the EPUB context.

[Madeleine Rothberg]

In the past, accessibility metadata efforts included a more general "this is accessible" property, which sounds like what Matt is describing. Ultimately I think we decided it was too vague to be useful, and more likely to be incorrectly set than a more specific property like accessibilityAPI.

For EPUB's purpose, seeking conformance with the EPUB Accessibility Conformance requirements shows an Author's intent to create an accessible experience. Maybe that is enough.

-Madeleine

[Matt Garrish]

> Perhaps a clearer conception of the use cases would help me to understand what you have in mind here.

The intention of setting the property now is to indicate that there is dynamic content that has been built to ARIA guidelines. Granted, that doesn't necessarily equate to accessible (perhaps controllable is more appropriate). If accessibilityAPI is isolated to describing the applications where they are embedded, which is what I read you were suggesting, what indication does the user have that any effort has been made to make such interactive content accessible? It would require processing the content to determine.

If we rely on content conforming to the specification to indicate ARIA requirements have been followed, we're leaving out the case of providing rich metadata for content that doesn't fully conform. So, my question is if the metadata is buried in the content, how do we still relay to the user what has been done?

The technique for accessibilityAPI starts off by stating that you only need to pay attention to the scripted interactivity case, as content authors don't control interaction with the platform APIs, so in that regard I think we're fine now.

Matt

-----Original Message-----
From: epub-work...@googlegroups.com [mailto:epub-work...@googlegroups.com] On Behalf Of White, Jason J
Sent: September 7, 2016 9:50 AM
To: epub-work...@googlegroups.com
Subject: RE: [EPUB][A11y] schema:accessibilityAPI

[White, Jason J]

> -----Original Message-----
> From: epub-work...@googlegroups.com [mailto:epub-working-

> gr...@googlegroups.com] On Behalf Of Matt Garrish

> > Perhaps a clearer conception of the use cases would help me to understand
> what you have in mind here.
>
> The intention of setting the property now is to indicate that there is dynamic
> content that has been built to ARIA guidelines. Granted, that doesn't necessarily
> equate to accessible (perhaps controllable is more appropriate). If
> accessibilityAPI is isolated to describing the applications where they are
> embedded, which is what I read you were suggesting, what indication does the
> user have that any effort has been made to make such interactive content
> accessible? It would require processing the content to determine.

[Jason] Suppose accessibilityAPI asserts ARIA conformance. Isn't that enough to establish the accessibility of the embedded interactive Web-based content in such cases? Alternatively, if the entire publication conforms to the EPUB Accessibility specification, then WCAG 2.0 Guideline 4.1 covers the accessibility of the embedded interactive components.
Unfortunately, I still don't understand where your issue lies, given these possibilities.

For the user (or someone working on behalf of the user), it is necessary to know what the client-side software needs to support in order to take advantage of the accessibility. This is easy in the case of ARIA, but for other embedded, interactive content it isn't so clear, which is why I prefer more specific properties such as accessibilityAPI that tell you what you need to have in place for it to work, rather than a more general "interactive accessibility" assertion.

[Matt Garrish]

> Suppose accessibilityAPI asserts ARIA conformance. Isn't that enough to establish the accessibility of the embedded interactive Web-based content

Yes, that's what Madeleine and I were suggesting. I agree that although you're not directly calling API functions, it still fits the purpose. But I read your earlier response as stating this isn't needed and that it should be described at the content document level.

If you're suggesting that we keep accessibilityAPI in the package document and tighten it up as primarily applicable to ARIA, and focus only on that for the techniques, we're on the same page. We're mostly there at this point, too, although I see some pruning that could be done to the technique.

Matt

-----Original Message-----
From: epub-work...@googlegroups.com [mailto:epub-work...@googlegroups.com] On Behalf Of White, Jason J
Sent: September 7, 2016 10:23 AM
To: epub-work...@googlegroups.com
Subject: RE: [EPUB][A11y] schema:accessibilityAPI

[White, Jason J]

> -----Original Message-----
> From: epub-work...@googlegroups.com [mailto:epub-working-
> gr...@googlegroups.com] On Behalf Of Matt Garrish
> Yes, that's what Madeleine and I were suggesting. I agree that although you're
> not directly calling API functions, it still fits the purpose. But I read your earlier
> response as stating this isn't needed and that it should be described at the
> content document level.
>
> If you're suggesting that we keep accessibilityAPI in the package document and
> tighten it up as primarily applicable to ARIA, and focus only on that for the
> techniques, we're on the same page. We're mostly there at this point, too,
> although I see some pruning that could be done to the technique.

[Jason] Yes, that's what I was explicitly suggesting earlier as my preferred solution: leave the property in place, state clearly that most of the values aren't usually applicable in the EPUB context, and illustrate its use in asserting ARIA support by embedded scripts.

If the accessibilityAPI property weren't in schema.org but was instead an EPUB-defined property, then there would be a stronger argument for confining the permissible values to "ARIA". However, as we know, it isn't an EPUB-defined property; it has much wider applicability - we're just using it here, not creating it.

[Romain]

> On 07 Sep 2016, at 16:42, White, Jason J <jjw...@ets.org> wrote:
>
>> If you're suggesting that we keep accessibilityAPI in the package document and
>> tighten it up as primarily applicable to ARIA, and focus only on that for the
>> techniques, we're on the same page. We're mostly there at this point, too,
>> although I see some pruning that could be done to the technique.

+1 (and thanks everyone for the discussion and clarification).

> [Jason] Yes, that's what I was explicitly suggesting earlier as my preferred solution: leave the property in place, state clearly that most of the values aren't usually applicable in the EPUB context, and illustrate its use in asserting ARIA support by embedded scripts.
>
> If the accessibilityAPI property weren't in schema.org but was instead an EPUB-defined property, then there would be a stronger argument for confining the permissible values to "ARIA". However, as we know, it isn't an EPUB-defined property; it has much wider applicability - we're just using it here, not creating it.

Yeah, it's almost unfortunate, since it may be confusing at first sight.
Maybe it's too late a change at this stage, but it sounds to me that ARIA support would be better declared as an accessibilityFeature.

Romain.

[White, Jason J]

> -----Original Message-----
> From: epub-work...@googlegroups.com [mailto:epub-working-

> gr...@googlegroups.com] On Behalf Of Romain
> Yeah, it's almost unfortunate, since it may be confusing at first sight.
> Maybe it's too late a change at this stage, but it sounds to me that ARIA support
> would be better declared as an accessibilityFeature.

[Jason] One could develop that idea even further and declare all of the accessibility APIs as permissible values of accessibilityFeature, eliminating accessibilityAPI altogether.

Would that be any less confusing than what we now have?

Note also the proposal (to be discussed at the upcoming ARIA Working Group meeting) to create a JavaScript-based accessibility API for the Web platform. See the early draft document at http://a11y-api.github.io/a11y-api/spec/
for one concrete realization of this idea.

Even if ARIA isn't strictly an accessibility API now, it may evolve into one, or become closely aligned with one; and as others have noted, it is directly mapped to the accessibility API of each operating system in accordance with the soon to be normative Accessibility API Mapping guides.

To be clear, I'm retaining my support for keeping accessibilityAPI as is and noting its proper usage in the EPUB techniques.