how to extract aria roles, states and properties

[jnurthen]

It would be great to be able to extract the ARIA roles, states and properties into webref so they could be better referenced by other specs. I'd like some advice as to the best way to make this happen.
ARIA uses respec so we could simply add them as a <dfn class="export"> but I'm not sure this is the best path forward.
We would like to create reference-able links for all of the following:

• The roles defined in https://w3c.github.io/aria/#role_definitions
• The states & properties (aria- attributes) defined in https://w3c.github.io/aria/#state_prop_def

If a dfn is the best way I can do that but if something else I'm happy to make other changes to the spec to enable something better.

Thanks

[tidoust]

Hi @jnurthen,

ARIA uses respec so we could simply add them as a <dfn class="export"> but I'm not sure this is the best path forward.

Using a <dfn> is definitely the right approach but the definitions need to have the right definition type and scope, specified with data-dfn-type and data-dfn-for attributes.

ReSpec's documentation seems out of date: ReSpec is aligned with the definitions data model and definition types described in Bikeshed's documentation in practice. In particular, you're not restricted to dfn and idl definitions.

As far as I can tell, ARIA states & properties are attributes for elements. Correct definition type is going to be element-attr. One difficulty is that an attribute definition needs to define what element it is relative to, and there is no specific element here. Looking at the HTML spec, I see it uses global to define id, html-global for title, and essentially nothing for role. It may be good to reuse global or html-global but the actual name may not matter much and it's ok if it does not have an element definition (there is no element definition for global and html-global). Just note that ReSpec needs something, otherwise references won't work as expected.

Roles are attribute values for the role attribute. Correct definition type is attr-value. Correct scope is going to be something like global/role (reusing the element name you're going to use for other attributes). As above, Respec needs the two levels, otherwise references won't work as expected.

ReSpec automatically exports definitions whose type is not dfn. No need to add class="export".

Once definitions are in place, they can be referenced within the spec, and the crawler will pick them up and add them to the cross-references database. References should use the [^...^] shorthand. Note ReSpec automatically wraps references in <code> when you use the shorthand syntax.

In short, the spec's source should look like:

<p>State/Property definition:
  <code><dfn data-dfn-type="element-attr" data-dfn-for="global">aria-atomic</dfn></code>
</p>
<p>Role definition:
  <code><dfn data-dfn-type="attr-value" data-dfn-for="global/role">alert</dfn></code>
</p>

<p>State/Property reference: [^global/aria-atomic^]</p>
<p>Role reference: [^global/role/alert^]</p>

[daniel-montalvo]

Thanks much @tidoust for such a clear explanation. the ARIA Editors will work on this and will come back to this if there are further questions.

I am happy to put a PR on respec to update the docs, as i do find myself having to resort to these when debugging. Now I know this part was outdated and this is why I was banging my head against the wall on some occasions :-). I think it would be good to have the dfn-type and dfn-for allowed values handy in respec itself.