Create description (was:definition) list role

[michael-n-cooper]

In 15 December 2016 teleconference create roles for HTML definition lists and its children.

Note this may be instead of the proposal to expand lists in #503.

[jasonkiss]

Posting here as this is the latest relevant issue. Apologies in advance for its length, and should you read it, thank you: I find this one particularly complicated, if only because of the names of the roles and elements involved.

TL;DR: the ARIA roles, term and definition, and their relationship to the HTML dfn, dl, dt, and ddelements are somewhat confused. Sorting this out is presumably planned for ARIA 1.2, but I don't think it's as straightforward as recent discussions/issues present. What follows is an attempt to identify some of the confusion and suggest some possible approaches.

Note that there are currently several issues related to the HTML dfn and definition/description list elements, and related ARIA roles, in both this repo (#455, #477, #497, #503, and this one) and the HTML-AAM repo (#6, #8, #51, #78).

Some definitions

HTML elements

Here are the definitions for the relevant elements in the HTML spec:

• dfn: defining instance of a term
• dl: description list of term-description groups
• dt: a term (part of a term-description group) in a dl
• dd: a description (part of a term-description group) in a dl

Note that a term-description group can include not only terms and their definitions, but also questions and answers, categories and topics, etc.

ARIA roles

Until new roles are created, here are the two relevant ARIA roles and their descriptions in the spec:

• definition: definition of a term or concept (related concept dd and dfn[sic])
• term: word or phrase with corresponding definition (related concept dt)

Comments

Assuming I've understood these element and role definitions correctly, as well as the current mappings for the definition and term roles in the Core-AAM, and the current actual mappings in accessibility APIs for the above four HTML elements, I note that:

• the name of the dfn element makes one think definition, but it is for a term being defined, which isn't intuitive
• mapping dfn to the term role makes sense, since they both identify a term being defined
• a dfn is clearly not a definition, so mapping it to the definition role, or including dfn as a related concept to the definition role, does not make sense
• mapping dt to the term role isn’t a clear fit, since the dt will not always be a term with a definition: it might just be a question or some other word or phrase with some kind of associated description. And the term role has no list semantics, while dt does.
• mapping dd to the definition role does not make sense because it is not necessarily a definition of a term: it might just be an answer to a question or some other description associated with some word or phrase.

A proposal

For the sake of proposing some possible solutions, at least as a place to start, I suggest we could, as a first step, take the lead from ATK and AX, and create an ARIA descriptionlist role (as opposed to a definitionlist role as discussed in the 15 December 2016 teleconference). IA2 could create IA2_ROLE_DESCRIPTION_LIST, and UIA a Localized Control Type for dl, e.g. “description list”.

Then I see two options.

• Option 1: try to reuse the existing roles as much as possible
• Option 2: clearly distinguish between a simple term and definition relationship, and the list context of one or more term-description groups (which could include term-definition groups, but with the added list semantics).

Option 1

If we go with option 1, reusing the existing roles as much as possible:

• we could expand the definition of the term role to allow its use for dfn as a defining instance of a term with a definition, but also for dt in term-description groups. In both cases, there’s a clear relationship between a word or phrase being further defined/described.
• we could expand the definition of the definition role to allow its use for definitions and descriptions in term-description groups. (Would we also want a new HTML element to match this role in contexts outside a dl, e.g. a new definition element, as it currently doesn't exist? More on this below.)
• we would likely want a way to identify the relationship between a term and its definition, which could be one to many, given that one dt can have multiple associated dd elements.

This would give us the following HTML to ARIA equivalencies/mappings:

• dl maps to a new descriptionlist role
• dt and dfn map to term
• dd (and optionally some new type of HTML element for definitions) maps to definition

Option 2

Or perhaps the list semantic of term-description groups is such that some new or different roles make option 2 better:

• keep the term role for dfn (or replace it with something like definitionterm)
• add a descriptionterm role for dt and give it a list semantic
• keep the definition role (or rename to termdefinition for consistency) for definitions associated with a dfn element or term role, and add a termdescription role for dd.
• establish a mechanism to relate a term and its definition, and to group or relate a dt with its one or more associated dd elements.

This would leave us with the following scenarios of equivalencies/mappings:

• dfn maps to the existing term role or a new definitionterm role
• dl maps to a new descriptionlist role
• dt maps to a new descriptionterm role
• dd maps to a new termdescription role

A new HTML element?

The interest in having equivalents in ARIA for all HTML semantics highlights a gap in HTML: While ARIA has the term and definition roles, there is no HTML element that identifies the definition associated with the dfn element. Currently a dfn element's associated definition is determined by the dfn element's nesting, specifically the "term-description group, p, li or section element that is the nearest ancestor of the dfn element."

What about introducing a definition element that could mirror the ARIA definition role? Then dfn could match the term roles, and a new definition element the definition role?

Or better, what about redefining the dfn element as the definition for a new term element? Reviewing a grep of dfn in a dump from webdevdata.org suggest that dfn is not used that often, and when it is, it is almost never used correctly. Additionally, except for WebKit's current incorrect mapping to of dfn to AXDefinition, and UIA's incorrect localized control type of "definition", dfn has no semantics. So repurposing/redefining dfn to represent a definition associated with a new term element might be an option without too much ill effect.

[schne324]

Option 2 makes the most sense to me but I feel that descriptiondetails is a better name for the new role that dd would map to

[johnfoliot]

I personally think part of the problem was that with HTML, the <DL> element was "renamed". In HTML 4 (and earlier) it was *normatively called the Definition List* ( https://www.w3.org/TR/html401/struct/lists.html#h-10.3) In HTML 5 however, it was (somewhat unofficially) renamed to "Description List" ( https://www.w3.org/TR/2011/WD-html5-author-20110809/the-dl-element.html) NOTE: HTML 5 normatively calls this the *dl element*, but in the associated normative prose it parenthetically calls these types of name-value group lists a description list, which gets us to where we are today. (One could argue that it was a missed 'typo' in the transition from HTML 4.x to HTML 5, but in the end, does it really matter?) ******************** Looking over your proposal Jason, I prefer the direction proposed in Option 2, although I'd want to ensure that at least at the Accessibility API level the HTML 4 and 5 specs arrive at the same semantic, English terms aside. My reading of the HTML 5 spec definition of <dfn> however is that *<dl>* and <dfn> should be semantically equal, although, as you note, <dfn> is rarely used, and almost never correctly. (I wonder aloud if web platforms might obsolete that as well, as they have done in the past with other under-used or incorrectly used elements and attributes). However, the spec is still somewhat unclear, but by examining the examples you could conclude that <dfn> is a truncated <dl>, in that it too seemingly contains both the term and the description, as illustrated in the HTML 5 spec <https://www.w3.org/TR/2011/WD-html5-author-20110705/the-dfn-element.html>: <dfn><abbr title="Garage Door Opener">GDO</abbr></dfn> (where the value of the title attribute *IS* the definition of the abbreviation GDO, per the spec) ...which I can also interpret 'semantically' as: <dl> <dt>GDO</dt> <dd>Garage Door Opener</dd> </dl> (although rendered on screen quite differently, and used slightly differently in context). None the less, both <dfn> and <dl> appear to be 'parent' elements that contain both the term and the definition, albeit using different methods, but ultimately arriving at the same place: a defined term. Does anyone else see it that way? JF

…

On Wed, Sep 19, 2018 at 10:38 AM, Harris Schneiderman < ***@***.***> wrote: Option 2 makes the most sense to me but I feel that descriptiondetails is a better name for the new role that dd would map to — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#504 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABK-c3LVbg22N76wl_daNI8cdGxQQ3bvks5ucmTkgaJpZM4LOb31> .

-- *John Foliot* | Principal Accessibility Strategist Deque Systems - Accessibility for Good deque.com

[jongund]

I think the most compatible step forward based on other roles, like menu/menuitem is to create two new roles within the content of the list role:

• listitemterm
• listitemdescription

These roles would only be allowed within the content of list and have the same pattern as menuitem, menutiemcheckbox and menuitemradio.

I will work on branch based on the addition of listiemterm and listitemdescription.

[johnfoliot]

A related yet also slightly off-topic question/comment. Is there a particular reason why the proposal is for such a compounded new attribute? Why @listitemterm and not @listterm? I pose this question in part based upon an observation (with no offense to Jon BTW...) - that Jon made two typos of these terms in one email: ...menutiemcheckbox and menuitemradio. ...the addition of listiemterm and listitemdescription. From a semantic perspective, would not a list term also be (by extension) a list item? (i.e. List item, type="term") Why do we need to make a compounded explicit naming notation when an implied naming notation would likely suffice? Signed, Curious in Austin JF

…

On Fri, Apr 12, 2019 at 9:50 AM Jon Gunderson ***@***.***> wrote: I think the most compatible step forward based on other roles, like menu/menuitem is to create two new roles within the content of the list role: - listitemterm - listitemdescription These roles would only be allowed within the content of list and have the same pattern as menuitem, menutiemcheckbox and menuitemradio. I will work on branch based on the addition of listiemterm and listitemdescription. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#504 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABK-c1PoZGk_jj-cDI5PUq0nDPjDDORgks5vgJ0-gaJpZM4LOb31> .

-- *​John Foliot* | Principal Accessibility Strategist | W3C AC Representative Deque Systems - Accessibility for Good deque.com

[jnurthen]

I think the most compatible step forward based on other roles, like menu/menuitem is to create two new roles within the content of the list role:

* listitemterm

* listitemdescription

These roles would only be allowed within the content of list and have the same pattern as menuitem, menutiemcheckbox and menuitemradio.

I will work on branch based on the addition of listiemterm and listitemdescription.

Would someone be allowed to mix and match listitem, listitemterm and listitemdescription? My thought is no - and if not how would we prevent this from happening?

[jnurthen]

I really think we need a different role for this. The mappings for DL in HTML are not the same as OL and UL. I'm not sure implementors will want to map this differently based on the child items. My gut feeling is that we need a descriptionlist role - or at a minimum we need a listtype attribute which could allow different accessibility API mappings for the list depending on the listtype.
I lean towards @jasonkiss Option 2 above.

[mcking65]

It seems there is a strong preference for Jason's option 2. And, I agree that we need an ARIA equivalent to dl.

That said, since the primary argument for adding 3 roles instead of 1 is to provide clear list semantics for the children of definitionlist, I find the role names of descriptionitem and descriptionterm really confusing. We either neither need to go all out and name them descriptionlistterm and descriptionlistdescription, or emphasize the list semantics by shortening them to dlistterm and dlistdescription. The word list is essential in all 3 roles. In fact, I would support a role name of dlist instead of descriptionlist.

[jongund]

@mcking65 I like the idea of using dlist role instead of descriptoinlist. My main concern with including list in the term role is that there will be two "t"'s in a row: dlistterm. But maybe that is not so bad, what do other people think?

Can we move this discussion to Pull Request 951.

[mcking65]

HTML just makes this messy. I think a more clear structure would be (using short hand that omits the div tags and role attributes):

<descriptionlist>
  <listitem>
    <term>...</term>
    <definition>...</definition>
  </listitem>
</descriptionlist>

If we adopted a structure like that, we could reuse the term and definition roles; they would have additional meaning when they are a descendant of a listitem. You also would not need IDs to associate the definition with the term.

[jongund]

@mcking65 I think the nesting of of term and definition in listitem will be confusing to authors and has not HTML5 equivalent for authoring and overloading term and definition with other meanings will again be confusing to authors.

Can we move this discussion to Pull Request 951.

[scottaohara]

since 951 was merged, can this issue be closed?