Add definition for implicit/explicit ARIA attributes #2154

Jym77 · 2024-01-11T10:42:16Z

Add a definition for "ARIA attribute is set", with variations whether it comes from an explicit aria-* attribute, an implicit HTML AAM, or a default value.
Switch "role has all required ARIA attributes" to also apply to implicit roles. These normally have implicitly set attributes (which is why we skipped them initially), and can now be handled by this definition.
Switch "role has all required ARIA attributes" to accept attributes set in any way.
Switch "ARIA attribute permitted" to only look at explicitly set ones. It was more or less already doing that by looking at aria-* HTML attributes, this makes it a bit clearer.

Closes issue(s):

closes Required states can come from native elements [4e8ab6] #2138

Need for Call for Review:
This will require a 2 weeks Call for Review (significant changes to Applicability)

Pull Request Etiquette

When creating PR:

Make sure you're requesting to pull a branch (right side) to the develop branch (left side).
Make sure you do not remove the "How to Review and Approve" section in your pull request description

After creating PR:

Add yourself (and co-authors) as "Assignees" for PR.
Add label to indicate if it's a Rule, Definition or Chore.
Link the PR to any issue it solves. This will be done automatically by referencing the issue at the top of this comment in the indicated place.
Optionally request feedback from anyone in particular by assigning them as "Reviewers".

When merging a PR:

Close any issue that the PR resolves. This will happen automatically upon merging if the PR was correctly linked to the issue, e.g. by referencing the issue at the top of this comment.

How to Review And Approve

Go to the “Files changed” tab
Here you will have the option to leave comments on different lines.
Once the review is completed, find the “Review changes” button in the top right, select “Approve” (if you are really confident in the rule) or "Request changes" and click “Submit review”.
Make sure to also review the proposed Call for Review period. In case of disagreement, the longer period wins.

_rules/aria-state-or-property-permitted-5c01ea.md

_rules/role-required-states-and-properties-4e8ab6.md

giacomo-petri · 2024-01-19T11:01:54Z

pages/glossary/aria-attribute-set.md

+  - DOM tree
+---
+
+An ARIA [state][aria state] or [property][aria property] is <dfn>set</dfn> on an [HTML element][namespaced element] when it has a value. This may happen in three ways:


The term "value" brings to mind the explicit value of an attribute. What if we replace it with "when the accessibility tree exposes its value."

This proved tricky, especially in combination of #2154 (comment) 😅

TLDR: DOM/HTML define the "value" of an attribute as the stuff written in the HTML code, which differs from our "attribute value", making everything hard to write. Here, we want to refer to the "value as written" since, presumably, the incorrect values could be dropped by parsing/validation and thus not make it to the "attribute value". Plus, as @carlosapaduarte stated, we do want rules to validate the "value as written" and thus not really bake it into this definition

Anyway, I tried to improve the situation…

pages/glossary/aria-attribute-set.md

carlosapaduarte

In addition to Giacomo's comments, I've added some more.

_rules/role-required-states-and-properties-4e8ab6.md

carlosapaduarte · 2024-01-25T11:18:57Z

pages/glossary/aria-attribute-set.md

+
+An ARIA [state][aria state] or [property][aria property] is <dfn>set</dfn> on an [HTML element][namespaced element] when it has a value. This may happen in three ways:
+
+- It is <dfn id="aria-attribute-set:explicit">explicitly set</dfn> if there is a corresponding `aria-*` HTML attribute on the element, whose value is valid for this ARIA [state][aria state] or [property][aria property].


"whose value is valid for this ARIA state or property"
Shouldn't this be checked by ARIA state or property has valid value?

See #2154 (comment)

carlosapaduarte · 2024-01-25T11:30:39Z

pages/glossary/aria-attribute-set.md

+
+  For example, `aria-checked` is implicitly set on `<input type="checkbox" checked />`.
+
+- It is <dfn id="aria-attribute-set:default">set by default</dfn> if there is no corresponding `aria-*` HTML attribute on the element, and the element has an [implicit semantic role][implicit role] that has a default value for this ARIA [state][aria state] or [property][aria property].


It is really hard to differentiate between implicitly set and set by default according to these definitions (the later is a subset of the former). Do we really need two definitions? Can we just have explicitly and implicitly set in the "Element with role attribute has required states and properties" rule?

Indeed, definition was a bit weak. I do believe these are still different and it might be valuable to be able to speak about one or the other (maybe not immediately, though…)
I improved the definition to make the difference more obvious. It is still a bit of a weak difference (depends which specs is setting it, essentially…) 🤷

Changes done

pages/glossary/aria-attribute-set.md

_rules/aria-state-or-property-permitted-5c01ea.md

CLAassistant · 2024-02-29T13:04:09Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

Carlos Duarte seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

_rules/aria-state-or-property-permitted-5c01ea.md

tbostic32 · 2024-03-27T21:18:35Z

_rules/aria-state-or-property-permitted-5c01ea.md

@@ -64,6 +64,8 @@ The presence of prohibited ARIA attributes is often the result of a developer us

 In HTML, there are language features that do not have corresponding implicit WAI-ARIA semantics. As per [ARIA in HTML](https://www.w3.org/TR/html-aria/), those elements can have [global states or properties][global]. Some of those elements can also have [inherited][], [supported][], or [required][] [states][state] or [properties][property] that correspond to a [WAI-ARIA role](https://www.w3.org/TR/wai-aria-1.2/#introroles). For example, the `audio` element has no corresponding ARIA semantics but it can have [inherited][], [supported][], or [required][] [states][state] or [properties][property] of the [`application` role](https://www.w3.org/TR/wai-aria-1.2/#application).

+This rule only applies to [explicitly set][aria set explicit] attributes since these have been provided by authors and using the wrong one is therefore an author issue. If an [implicitly set][aria set implicit] attribute is incorrect, this is not necessarily an author error, e.g., it can be the result of re-purposing an existing element.


Would this not still be a responsibility of the author to ensure the attributes are correct? It could still lead to violations, does the ARIA state or property has valid value check for this? If so, I think we should just call that out directly.

If only it was so simple 😞

<input type="checkbox" role="button" aria-pressed="false" /> is allowed by ARIA (as far as I can tell), but has an implicit aria-checked set by checked (automagically set on <input type="checkbox" />), which is not allowed on a role of button…

An implicit attribute doesn't show up in the code, rather, it is only added automatically by a user agent during accessibility API mapping. A checker using the rule would never pick up any implicit attribute. Therefore, it's not necessary to call out the implicit attribute for the purpose of a rule.

Code fixed.

carlosapaduarte

Minor edits suggested

pages/glossary/aria-attribute-set.md

Co-authored-by: Carlos Duarte <[email protected]>

…states

zlayaAvocado · 2025-05-30T18:39:40Z

_rules/aria-state-or-property-permitted-5c01ea.md

+This `button` does not have any [explicitly set][aria set explicit] ARIA attribute. It has an [implicitly set][aria set implicit] `aria-checked` state, due to the [absence of a `checked` attribute][checked absent] on the `input` element with a `type` [attribute value][] of `checkbox`.
+
+```html
+<input type="checkbox" role="button" />


isn't this supposed to be used together with aria-pressed if role="button" type="checkbox"? https://www.w3.org/TR/html-aria/#el-input-checkbox

No need to mention the implicit attribute "aria-checked" because it doesn't exist in the code that a checker runs on.

zlayaAvocado · 2025-05-30T19:06:09Z

_rules/role-required-states-and-properties-4e8ab6.md

+
+#### Passed Example 8
+
+This `menuitemcheckbox` has its required `aria-checked` property [implicitly set][aria set implicit].


Suggested change

This `menuitemcheckbox` has its required `aria-checked` property [implicitly set][aria set implicit].

This `menuitemcheckbox` has its required `aria-checked` property [implicitly set][aria set implicit] because type="checkbox" is set on the element.

If I am correctly understanding, aria-checked is only set because of type="checkbox"? Should this be clarified and then a failed example created (if we don't have one already)?

This menuitemcheckbox does not have its required aria-checked property [implicitly set][aria set implicit].

<label> <input role="menuitemcheckbox" /> Check me </label>

zlayaAvocado · 2025-05-30T19:35:00Z

_rules/role-required-states-and-properties-4e8ab6.md

+
+#### Passed Example 9
+
+This `iframe` element is [included in the accessibility tree][], even without a role, and therefore has no [WAI-ARIA required states and properties][].


trying to figure out this example, is it to clarify that role is not a requirement for this rule as long as other required properties are set (if the element is in the accessibility tree)?

zlayaAvocado · 2025-05-30T19:40:29Z

_rules/role-required-states-and-properties-4e8ab6.md


 ```html
 <div>Some Content</div>
 ```

 #### Inapplicable Example 2

-This `checkbox` has an [implicit semantic role](#implicit-role) that is identical to the [explicit semantic role](#explicit-role). This allows native HTML `checked` attribute to apply.


can you explain why this was removed?

zlayaAvocado · 2025-05-30T19:52:07Z

pages/glossary/aria-attribute-set.md

+
+- It is <dfn id="aria-attribute-set:explicit">explicitly set</dfn> if there is a corresponding `aria-*` HTML attribute on the element. If the [value][html attribute value] written in the HTML code is not valid for this ARIA [state][aria state] or [property][aria property] then the attribute is set but does not have an [attribute value][].
+
+  For example, `aria-label` is explicitly set on `<button aria-label="Next page">Next</button>`; and `aria-checked` is explicitly set on `<input type="checkbox" aria-checked="yes" />`, even though it does not have an [attribute value][].


just wondering if it would be better to use a different example for <input type="checkbox" aria-checked="yes" /> since these attributes generally shouldn't be used together and the value of checked will be false on the accessibility tree

shunguoy · 2025-06-04T03:25:46Z

_rules/aria-state-or-property-permitted-5c01ea.md

@@ -64,6 +64,8 @@ The presence of prohibited ARIA attributes is often the result of a developer us

 In HTML, there are language features that do not have corresponding implicit WAI-ARIA semantics. As per [ARIA in HTML](https://www.w3.org/TR/html-aria/), those elements can have [global states or properties][global]. Some of those elements can also have [inherited][], [supported][], or [required][] [states][state] or [properties][property] that correspond to a [WAI-ARIA role](https://www.w3.org/TR/wai-aria-1.2/#introroles). For example, the `audio` element has no corresponding ARIA semantics but it can have [inherited][], [supported][], or [required][] [states][state] or [properties][property] of the [`application` role](https://www.w3.org/TR/wai-aria-1.2/#application).

+This rule only applies to [explicitly set][aria set explicit] attributes since these have been provided by authors and using the wrong one is therefore an author issue. If an [implicitly set][aria set implicit] attribute is incorrect, this is not necessarily an author error, e.g., it can be the result of re-purposing an existing element.


An implicit attribute doesn't show up in the code, rather, it is only added automatically by a user agent during accessibility API mapping. A checker using the rule would never pick up any implicit attribute. Therefore, it's not necessary to call out the implicit attribute for the purpose of a rule.

shunguoy · 2025-06-04T03:32:38Z

_rules/aria-state-or-property-permitted-5c01ea.md

+This `button` does not have any [explicitly set][aria set explicit] ARIA attribute. It has an [implicitly set][aria set implicit] `aria-checked` state, due to the [absence of a `checked` attribute][checked absent] on the `input` element with a `type` [attribute value][] of `checkbox`.
+
+```html
+<input type="checkbox" role="button" />


No need to mention the implicit attribute "aria-checked" because it doesn't exist in the code that a checker runs on.

shunguoy · 2025-06-04T03:36:03Z

_rules/role-required-states-and-properties-4e8ab6.md

-For each test target, the [WAI-ARIA required states and properties][] for the role are set and not empty (`""`), unless the state or property has a default value listed under [WAI-ARIA implicit value for role][].
+For each test target, the [WAI-ARIA required states and properties][] for the role are [set][aria set] and not empty (`""`).
+
+The attributes may be [explicitly set][aria set explicit], [implicitly set][aria set implicit], or [set by default][aria set default].



same with my early comment, an implicit attribute doesn't show up in the code, and thus never picks up by a checker, so it's not necessary to include any implicit attribute.

Jym77 added 4 commits January 11, 2024 11:16

Add definition of ARIA attribute set

593ab3d

Use new definition in required states

07a1a6e

Use new definition in allowed states

6fe0f13

Clean up links

41324e8

Jym77 self-assigned this Jan 11, 2024

Jym77 added Rule Update Use this label for an existing rule that is being updated reviewers wanted labels Jan 11, 2024

Jym77 requested review from WilcoFiers, carlosapaduarte, dd8, tbostic32 and giacomo-petri January 11, 2024 10:42

giacomo-petri reviewed Jan 19, 2024

View reviewed changes

_rules/aria-state-or-property-permitted-5c01ea.md Outdated Show resolved Hide resolved

giacomo-petri reviewed Jan 19, 2024

View reviewed changes

_rules/role-required-states-and-properties-4e8ab6.md Show resolved Hide resolved

giacomo-petri reviewed Jan 19, 2024

View reviewed changes

pages/glossary/aria-attribute-set.md Outdated Show resolved Hide resolved

carlosapaduarte previously requested changes Jan 25, 2024

View reviewed changes

Carlos Duarte and others added 4 commits January 25, 2024 11:31

Merge branch 'develop' into implicit-explicit-states

0571507

Merge branch 'develop' into implicit-explicit-states

b3e4099

Clarify definition

0cf36b4

Typos

a18afec

Jym77 requested review from giacomo-petri and carlosapaduarte February 1, 2024 10:46

tbostic32 reviewed Feb 1, 2024

View reviewed changes

pages/glossary/aria-attribute-set.md Outdated Show resolved Hide resolved

pages/glossary/aria-attribute-set.md Outdated Show resolved Hide resolved

_rules/aria-state-or-property-permitted-5c01ea.md Outdated Show resolved Hide resolved

Merge branch 'develop' into implicit-explicit-states

1e1fa47

Jym77 added 2 commits February 29, 2024 14:20

Fix incorrect numbering

a44c668

Streamline text

4f135b6

Jym77 requested a review from tbostic32 February 29, 2024 13:21

tbostic32 previously requested changes Mar 27, 2024

View reviewed changes

Jym77 added 2 commits April 18, 2024 14:35

Merge branch 'develop' into implicit-explicit-states

1e54b3e

Fix code

bb7e66b

Jym77 requested a review from tbostic32 April 18, 2024 13:33

carlosapaduarte approved these changes Aug 1, 2024

View reviewed changes

pages/glossary/aria-attribute-set.md Outdated Show resolved Hide resolved

pages/glossary/aria-attribute-set.md Outdated Show resolved Hide resolved

Jym77 and others added 4 commits February 7, 2025 12:49

Typos

3f46f74

Co-authored-by: Carlos Duarte <[email protected]>

Merge remote-tracking branch 'origin/develop' into implicit-explicit-…

10ca88d

…states

Clean up

d598f7c

Clean up

a21542b

HelenBurge requested review from zlayaAvocado and shunguoy May 29, 2025 14:27

zlayaAvocado requested changes May 30, 2025

View reviewed changes

zlayaAvocado removed the reviewers wanted label May 30, 2025

shunguoy reviewed Jun 4, 2025

View reviewed changes


		An ARIA [state][aria state] or [property][aria property] is <dfn>set</dfn> on an [HTML element][namespaced element] when it has a value. This may happen in three ways:

		- It is <dfn id="aria-attribute-set:explicit">explicitly set</dfn> if there is a corresponding `aria-*` HTML attribute on the element, whose value is valid for this ARIA [state][aria state] or [property][aria property].


		For example, `aria-checked` is implicitly set on `<input type="checkbox" checked />`.

		- It is <dfn id="aria-attribute-set:default">set by default</dfn> if there is no corresponding `aria-*` HTML attribute on the element, and the element has an [implicit semantic role][implicit role] that has a default value for this ARIA [state][aria state] or [property][aria property].

		@@ -64,6 +64,8 @@ The presence of prohibited ARIA attributes is often the result of a developer us

		In HTML, there are language features that do not have corresponding implicit WAI-ARIA semantics. As per [ARIA in HTML](https://www.w3.org/TR/html-aria/), those elements can have [global states or properties][global]. Some of those elements can also have [inherited][], [supported][], or [required][] [states][state] or [properties][property] that correspond to a [WAI-ARIA role](https://www.w3.org/TR/wai-aria-1.2/#introroles). For example, the `audio` element has no corresponding ARIA semantics but it can have [inherited][], [supported][], or [required][] [states][state] or [properties][property] of the [`application` role](https://www.w3.org/TR/wai-aria-1.2/#application).

		This rule only applies to [explicitly set][aria set explicit] attributes since these have been provided by authors and using the wrong one is therefore an author issue. If an [implicitly set][aria set implicit] attribute is incorrect, this is not necessarily an author error, e.g., it can be the result of re-purposing an existing element.


		#### Passed Example 8

		This `menuitemcheckbox` has its required `aria-checked` property [implicitly set][aria set implicit].


		#### Passed Example 9

		This `iframe` element is [included in the accessibility tree][], even without a role, and therefore has no [WAI-ARIA required states and properties][].


		- It is <dfn id="aria-attribute-set:explicit">explicitly set</dfn> if there is a corresponding `aria-*` HTML attribute on the element. If the [value][html attribute value] written in the HTML code is not valid for this ARIA [state][aria state] or [property][aria property] then the attribute is set but does not have an [attribute value][].

		For example, `aria-label` is explicitly set on `<button aria-label="Next page">Next</button>`; and `aria-checked` is explicitly set on `<input type="checkbox" aria-checked="yes" />`, even though it does not have an [attribute value][].

Add definition for implicit/explicit ARIA attributes #2154

Are you sure you want to change the base?

Add definition for implicit/explicit ARIA attributes #2154

Uh oh!

Conversation

Jym77 commented Jan 11, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Etiquette

When creating PR:

After creating PR:

When merging a PR:

How to Review And Approve

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

carlosapaduarte left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CLAassistant commented Feb 29, 2024

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

carlosapaduarte left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Jym77 commented Jan 11, 2024 •

edited

Loading