definition-list-children-valid

Description lists must be structured correctly

automaticWCAG 1.3.1 (A)confidence: highseverity: seriousperceivable

Checks that <dl> elements only directly contain <dt>/<dd> groups (optionally wrapped in one <div>), <script>, <template>, or <style>.

Applies to. Applies to <dl> elements that have at least one direct element child or non-whitespace text directly inside them.

Expectation. Every direct element child is <dt>, <dd>, <script>, <template>, <style>, or a <div> whose own children are drawn from that same set (a single level of wrapping div is allowed, matching how authors commonly group dt/dd pairs). Non-whitespace text directly inside the <dl> or a wrapping <div> is an invalid child too. If the flattened set contains any <dt> or <dd> at all, it must contain BOTH (an unbalanced dt-without-dd or dd-without-dt is invalid), and read in order it must be groups of one or more <dt> followed by one or more <dd>: a <dd> before the first <dt> has no term, and a <dt> after the last <dd> has no definition. A flattened set with neither (an empty list, or one holding only <script>, <template> or <style>) is not a violation: the pairing is required only of a list that has items. Any other direct or wrapped child breaks the description-list semantics assistive technologies rely on. Every finding is reported at CANTTELL, not FAIL. HTML-AAM gives <dt> and <dd> their term and definition roles wherever they sit, so what a broken content model loses is the pairing of terms with definitions, which only the <dl>'s structure and order state. That is a WCAG failure (SC 1.3.1) only where the page shows the pairing, and H40 is only a sufficient technique: a person settles it.

What a finding reports.

invalidChildren: the children that do not belong in the list, one tag name per child (#text for text placed directly inside). Empty when the problem is a missing or misordered <dt>/<dd>.

These data.details fields help to read and reproduce a finding. Apart from reasonCode and the few fields Output schema names as stable, they are not a stable contract: a field may be renamed or dropped in a minor release, so don’t build on them.

Examples

pass

<dl>
  <dt>Term</dt>
  <dd>Definition</dd>
</dl>

<dl>'s only direct children are dt/dd.

can't tell

<dl>
  <dt>Term</dt>
  <dd>Definition</dd>
  <p>oops</p>
</dl>

The <p> is a direct child of <dl> that isn't dt/dd (or an allowed wrapper). The term and definition keep their roles, so whether a WCAG criterion fails depends on whether the page shows a pairing the markup breaks.

How to check

When this rule can’t decide, it reports cantTell and leaves the question to a person. Each question it can ask is listed here under its reason code, with the steps to answer it. A finding carries the same steps as howToCheck, in the scan’s language. See Output schema.

`DL_DT_DD_ORDER`

Inspect the description list the report names and note the definition that comes before the first term, or the last term with no definition after it.
Look at how the page shows the terms and definitions: whether each definition is shown as belonging to a term, by position, indentation or style.
With a screen reader, read the content and note whether each definition is announced with the term it belongs to.

Pass. The page shows no pairing that the markup loses: the terms and definitions are not shown as belonging together, or the markup still pairs them. Still fix the markup: HTML does not allow it.

Fail. The page shows a definition belonging to a term that the markup does not pair it with, so that relationship is not programmatically determinable (WCAG 1.3.1).

`DL_INVALID_CHILD`

Inspect the description list the report names and note the child that is not a <dt>/<dd> group, a single wrapping <div>, a script, template or style, or the text placed directly inside it.
Look at how the page shows the terms and definitions: whether each definition is shown as belonging to a term, by position, indentation or style.
With a screen reader, read the content and note whether each definition is announced with the term it belongs to.

Pass. The page shows no pairing that the markup loses: the terms and definitions are not shown as belonging together, or the markup still pairs them. Still fix the markup: HTML does not allow it.

Fail. The page shows a definition belonging to a term that the markup does not pair it with, so that relationship is not programmatically determinable (WCAG 1.3.1).

`DL_NO_DT_DD`

Inspect the description list the report names and note the terms with no definition, or the definitions with no term.
Look at how the page shows the terms and definitions: whether each definition is shown as belonging to a term, by position, indentation or style.
With a screen reader, read the content and note whether each definition is announced with the term it belongs to.

Pass. The page shows no pairing that the markup loses: the terms and definitions are not shown as belonging together, or the markup still pairs them. Still fix the markup: HTML does not allow it.

Fail. The page shows a definition belonging to a term that the markup does not pair it with, so that relationship is not programmatically determinable (WCAG 1.3.1).

View source