HTML parsing errors and the ADA

A criterion with a footnote

WCAG 2.1 Success Criterion 4.1.1 Parsing requires that, in content built with markup languages, elements have complete start and end tags, elements are nested according to their specifications, elements do not contain duplicate attributes, and any IDs are unique, except where the specifications allow these features.

Note in WCAG 2.1: "This success criterion should be considered as always satisfied for any content using HTML or XML." For HTML pages, this criterion therefore cannot fail on its own.

Status note. This criterion was removed from WCAG 2.2, so you will not find it in newer checklists. It is, however, part of WCAG 2.1, and WCAG 2.1 Level A and AA is the standard named by the ADA Title II web rule, so it is listed here. W3C's explanation says browsers now handle these markup errors in a defined way, so the criterion no longer provides a benefit to people with disabilities in itself. Clean markup is still worth the effort, because broken markup tends to cause failures of other criteria, such as 1.3.1 and 4.1.2, for example a label pointing at the wrong field.

Assistive technology builds its picture of a page from the same document tree the browser builds. When markup is malformed, the browser repairs it silently, and the repaired tree may not match what the author intended. Typical results are a form label attached to the wrong control, an aria-labelledby pointing at the first of two elements with the same ID, or a stray tag swallowing the rest of a page into a link.

In older or non-browser consumers, such as embedded viewers and some email and kiosk components, the tolerance is lower still.

Where public sites produce invalid markup

Most invalid markup on public sites comes from templates and loops, not from hand-written pages: a hold button repeated on every row of a library catalog, a server template that prints a name into an attribute without escaping, a content-management widget that stamps the same ID onto every instance. A page can look right while the structure underneath is wrong.

When a vendor supplies these templates, include markup validation in the acceptance checks rather than waiting for a complaint.

Duplicate IDs in repeated rows

Every row of a catalog result list got the same ID, so each aria-labelledby points at the first title on the page.

<li><span id="title">Maps of the Valley</span>
    <button aria-labelledby="title">Place hold</button></li>
<li><span id="title">Birds of the Coast</span>
    <button aria-labelledby="title">Place hold</button></li>

<li><span id="title-1042">Maps of the Valley</span>
    <button aria-labelledby="title-1042">Place hold</button></li>
<li><span id="title-1043">Birds of the Coast</span>
    <button aria-labelledby="title-1043">Place hold</button></li>

Nesting that the specification forbids

A link may not contain an interactive element such as a button. Browsers disagree about what to do with it, and assistive technology may announce one control or two.

<a href="/clinic/book"><button type="button">Book a visit</button></a>

<a class="button" href="/clinic/book">Book a visit</a>

Attribute problems from templates

A surname that contains a quote ends the attribute early and corrupts the rest of the tag. Escape every value that a template prints into markup.

<input name="surname" value="O"Brien">

<input name="surname" value="O&quot;Brien">

When two partial templates both add the same attribute, only one wins and the other is dropped, which can silently remove a hint or error reference.

<input id="vin" aria-describedby="vin-hint"
       aria-describedby="vin-error">

<input id="vin" aria-describedby="vin-hint vin-error">

Native apps

SwiftUI and Jetpack Compose describe screens with code, not tags, so this criterion has no direct equivalent in native screens. It does apply to any HTML shown inside a web view, such as a payment page or a help article loaded into the app.

Testing it

1. Run the page through a validator, such as the W3C Nu HTML Checker, or an HTML linter in your build.
2. Fix errors about unclosed elements, bad nesting, duplicate attributes and duplicate IDs first; these are the errors that break labels and references.
3. Search the rendered page for repeated IDs with a script or the developer tools console, for example by counting elements per ID.
4. Check that every for, aria-labelledby and aria-describedby target exists once.
5. Test the rendered DOM, not only the source, because scripts add and clone elements.

Common mistakes and a markup hygiene checklist

• Pasting a component twice and keeping its fixed ID.
• Fixing validation messages that are only style warnings while ignoring real errors.
• Trusting that the browser's repair gave the right result.
• Validating the template instead of the rendered output.

Hygiene that prevents failures of 1.3.1, 4.1.2 and others:

• No duplicate IDs on rendered pages, so labels and references resolve.
• Elements are properly closed, nested and free of duplicate attributes.
• Every ID reference points to exactly one element.
• Validation runs in the build or release checks.

For how markup issues connect to the standard, see WCAG 2.1 AA and the ADA.

Sources

• Understanding SC 4.1.1: Parsing (W3C), opens in a new tab
• 28 CFR Part 35, Subpart H: Accessibility of Web Information and Services (eCFR), opens in a new tab

Standard version: WCAG 2.1 (W3C Recommendation, 5 June 2018), as named in the Title II web rule. This page is for informational purposes only and is not legal advice. For binding requirements, refer to the official ADA statute and regulations, and ask a lawyer how they apply to you.