Mac "AX" property and value names in AAM specs

[jasonkiss]

Bringing this over from W3 bugzilla 28624.

With the updates to the Mac NSAccessibility protocol and related Apple developer documentation, do we need to reconsider how the mapping guides present the various properties and values for the Mac API?

In the current version of the Mac Accessibility Inspector, the properties are now called "accessibilityRole", "accessibilitySubrole", and "accessibilityRoleDescription". Despite the fact that the Inspector shows their values using the "AX" names, e.g. AXGroup, there's no clear documentation anywhere that I can find that lists the "AX" values. The old HTML to Platform Accessibility APIs Implementation Guide used to link to a page describing all the different "AX" values, etc., but that page doesn't exist anymore.

Should we be presenting these property names and values in a way that more closely aligns with how they are presented in the official NSAccessibility Protocol documentation? Do we leave things as they are but include a note regarding the way they are named, i.e. with the "AX" prefix?

Assigning to @cookiecrook for his input.

[cookiecrook]

The change seems reasonable to me. I'll discuss with the OS X team. FWIW, the "AX-prefixed" attributes are still exposed in the Inspector if you select View > Show Raw Attributes.

[cookiecrook]

Confirmed that it's okay to replace "AXRole", "AXSubrole", and "AXRoleDescription". with "accessibilityRole", "accessibilitySubrole", and "accessibilityRoleDescription".

Please leave the string values (e.g. "AXGroup") as-is for now, but I'm open to more discussion (Lisbon F2F?) of the pros and cons of referencing the public constants where they exist.

[jasonkiss]

That's great. Thanks.

What about how we're currently referring to the API itself, namely "Mac OS X Accessibility Protocol Mac OS 10.10 [AXAPI]"? Would it be more accurate to refer instead to "Mac NSAccessibility Protocol [NSAccessibility]"?

[cookiecrook]

What about how we're currently referring to the API itself, namely "Mac OS X Accessibility Protocol Mac OS 10.10 [AXAPI]"?

You typically don't see "Mac" used except in reference to the hardware. Maybe "OS X Accessibility Protocol [AX API]"?

[jasonkiss]

@cookiecrook

Sorry, more questions:

• If the "raw attributes" are the "AX"-prefixed ones, does that mean that the "accessibility"-prefixed attribute names are just friendlier aliases? If so, then I'm happy to stick with the "AX"-prefixed attribute names.
• Is "AX API" or "AXAPI" a critically meaningful string for implementers? I note that Google searches for "ax api" or "axapi" don't return any OS X related results on the first page, suggesting that those strings are sufficiently overdetermined, and insufficiently used to refer to the OS X A11y Protocol. If the API protocol is NSAccessibility, does it make sense to replace "AXAPI" with "NSAccessibility"? For example, "OS X Accessibility Protocol [NSAccessibility]"?

[cookiecrook]

If the "raw attributes" are the "AX"-prefixed ones, does that mean that the "accessibility"-prefixed attribute names are just friendlier aliases?

It's different versions of the API. The modern API uses the longer, friendlier names and (more importantly) is significantly easier to use, so let's make the AAM change.

Is "AX API" a critically meaningful string for implementers?

I guess not, but that's what it's called by all the internal and external engineers that work on it. "AX+API" site:apple.com

[jasonkiss]

Thanks @cookiecrook. So, to confirm:

• the "AX" prefixed attribute names, e.g. AXRole, will be replaced with the "accessibility" prefixed versions, e.g. accessibilityRole
• the attribute value strings will, for the time being, retain the "AX" form, e.g. AXGroup
• the API will be referred to as the "OS X Accessibility Protocol", with "AXAPI" as the short name, e.g. "OS X Accessibility Protocol [AXAPI]"

@michael-n-cooper @klown @AmeliaBR @richschwer Any concerns with this editorial change to the various AAM docs? Assuming not, I'm happy to create a branch and implement this change across all the relevant docs for your review.

[cookiecrook]

Confirmed. Thanks Jason.

[fredesch]

Jason,
We have 2 AAMs - SVG AAM https://github.com/w3c/aria/tree/master/svg-aam and the Graphics Module AAM https://github.com/w3c/aria/tree/master/graphics-aam that will need to be changed. Will you change these two AAMs as well?

We also have two wiki pages https://www.w3.org/wiki/SVG_Accessibility/Testing/Test_Assertions_with_Tables#Simple_name_testable_statements https://www.w3.org/wiki/SVG_Accessibility/Testing/Test_Assertions/Language_Tables which are used to convert to tests for the PF test harness. @joanmarie has made webkit layout tests which she notes on the wiki pages. I assume we will need to change the wiki pages, but will the layout tests need to be modified as well?

[joanmarie]

@fredesch: If the mappings change in such a way that the current WebKit implementation is no longer correct, then there will of course need to be a change in the WebKit code and the layout tests would be updated as part of that code change. But from a quick glance at the discussion here, that does not seem to be the case. Please correct me if I'm wrong.

[cookiecrook]

No WebKit change is required because both versions of the API are supported on OS X.

I believe Jason made the request because the documentation on the developer.apple.com site has been updated to recommend the latest version. I agree that is a reasonable change to make, and since this spec only reference 3 properties from the API, it's a trivial replace-all in the source file.

[jasonkiss]

@fredesch Yes, I'm happy to make a branch with the changes above to the following AAM and related docs as applicable:

• accname-aam
• core-aam
• css-aam
• dpub-aam
• graphics-aam
• html-aam
• svg-aam
• common/biblio.js
• common/terms.html

There's no need to change the attribute names used in the test assertion wiki pages, and I hadn't planned to update them, but I could, if consistency between the AAMs and the test assertions is preferred. Just let me know. As James suggest, and just as with the overall change recommended above, there's no change required to what the expected values will be for the various attributes.

[jasonkiss]

@cookiecrook

Quick one: In various AAM docs, we refer to AXDescription (as one option for mapping accname, depending on context). I'm assuming that the equivalent property in the latest version of the API is accessibilityLabel? Since I can no longer find the documentation for the older version of the API, I'm having to compare the values assigned for the two properties using the Accessibility Inspector. Ta.

Ok. Maybe not so quick. In looking at the property mappings in the core-aam and html-aam, there are bunch of "AX-" properties for which I cannot determine the "accessibility-" equivalent in the new API:

• AXARIAAtomic
• AXARIACurrent
• AXARIALive
• AXARIAPosInSet
• AXARIARelevant
• AXARIASetSize
• AXAccessKey
• AXLanguage
• AXGrabbed
• AXDropEffects
• AXElementBusy
• AXInvalid

The above list is probably incomplete.

Also, I'm assuming that action methods like AXShowMenu and AXPress have become accessibilityPerformShowMenu and accessibilityPerformPress.

As these are all names of properties/methods, as opposed to values, I'm under the impression that it is correct and consistent to change these as well to their names from the new version of the API? Otherwise, if the/your advice is not to update these property/method names, then I'd suggest we reconsider updating any of the names to the latest version of the API until we're ready to do all of them, at the very least to avoid confusion. But then again, the Apple documentation defining those older API property and method names no longer exists (that I can find), so I think we should update them all (including any relevant property value strings as well) as soon as possible.

[cookiecrook]

Yes, some of those properties don't have equivalents. Let's hold off on making any change.

[jasonkiss]

Ok. Will the new version of the API eventually include equivalents/replacements for those properties? What kind of time frame? In the meantime, since the AAM specs are still referring to it, where does one find publicly available documentation on the old version of the API?

[cookiecrook]

You have a way of asking short questions with extremely long answers. ;-) How about a discussion over dinner in Lisbon?

[jasonkiss]

I'd love to chat in Lisbon, but I won't be there :-(

The crux of my concern is that our AAM specs link to and document mappings for an API that Apple actively discourages. If we can't immediately fix this by pointing to and updating mappings for the newer, recommended API, I think we should at least add a note to all the AAM specs acknowledging the situation.

[cookiecrook]

Those are discouraged for native app developers, not rendering engine developers. A web rendering engine would not be possible using only the simpler protocol.

[jasonkiss]

Those sorts of distinctions and details aren't clear to me from any of the Apple documentation I can find, and aren't apparent in the AAM docs.

Can we add some text to the "Comparing Accessibility APIs" section of the CORE-AAM to help explain the relationship between the two APIs and how they apply in the context of rendering engine development? Is it possible that Apple might update its documentation to clarify these issues? Or is it just me who doesn't get it?

[joanmarie]

What is the status of this? Are we still holding off as per @cookiecrook's comment?

[cookiecrook]

For UA mappings, I'm leaning toward leaving as-is.

[jasonkiss]

I'm happy to take the steer from @cookiecrook, as I'm not familiar with the nuances of the MacOS/iOS/AXAPI/NSAccessibility ecosystem. But that lack of familiarity was part of the reason for my raising the issue in the first place. As a spec reader, I find that the variation in the way the AXAPI mappings relate to the available documentation at developer.apple.com and the API property and value names in Apple's Accessibility Inspector only makes it more difficult to grok, and I was hoping there might be an easy-ish way to rationalise their presentation in the AAMs, reducing that difficulty.

[cookiecrook]

Thanks @jasonkiss
Thanks for following up @joanmarie