# Accessibility Issues

> Canonical HTML version: https://rocketvalidator.com/docs/api/a11y_issues
> Attribution: Rocket Validator (https://rocketvalidator.com)
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

An Accessibility issue corresponds to an issue found on a given web page when being checked by the A11Y checker.

## Attributes

<dl>
  <dt>ID</dt>
  <dd>Unique ID for this issue.</dd>

  <dt>Help</dt>
  <dd>Brief description of the issue.</dd>

  <dt>Help URL</dt>
  <dd>URL where you can find more info about the issue and proposed fixes.</dd>

  <dt>URL</dt>
  <dd>URL of the document the issue refers to. Typically this is the URL of the related Web Page.</dd>

  <dt>HTML</dt>
  <dd>Code snippets showing the affected elements.</dd>

  <dt>Impact</dt>
  <dd>Severity of the issue.</dd>

  <dt>Impact Order</dt>
  <dd>Numerical representation of the Impact.</dd>

  <dt>Tags</dt>
  <dd>Comma-separated list of tags to categorize this issue.</dd>

  <dt>Inserted At</dt>
  <dd>Timestamp when the Accessibility Issue was created.</dd>

  <dt>Updated At</dt>
  <dd>Timestamp when the Accessibility Issue was last updated.</dd>

  <dt>Description</dt>
  <dd>Short plain-text explanation of the issue, from the Rocket Validator guide that matches it. Null when no guide matches. This is Rocket Validator's own explanation, and is separate from the Help attribute, which carries the text supplied by the accessibility engine.</dd>

  <dt>Description Markdown</dt>
  <dd>The same explanation in Markdown. Null when no guide matches.</dd>

  <dt>Description HTML</dt>
  <dd>The same explanation as rendered HTML. Null when no guide matches.</dd>

  <dt>Guide URL</dt>
  <dd>Link to the full guide for this issue. Null when no guide matches.</dd>
</dl>


> **Guide descriptions are not available for every issue**
>
> Rocket Validator publishes a guide for the most common issues, but not for
> every possible validator message. When no guide matches an issue, the four
> description and guide attributes are `null`. Treat them as optional.

## Relationships

<dl>
  <dt>Report</dt>
  <dd>The Report that this Accessibility Issue belongs to.</dd>

  <dt>Web Page</dt>
  <dd>The Web Page that this Accessibility Issue belongs to.</dd>
</dl>

## Example


> **Example: Accessibility Issue**
>
> ```json
> {
>   "data": {
>     "attributes": {
>       "description": "The names of ARIA attributes beginning with \"aria-\" must be correct.",
>       "description_markdown": "The names of ARIA attributes beginning with \"aria-\" must be correct.",
>       "description_html": "<p>The names of ARIA attributes beginning with &quot;aria-&quot; must be correct.</p>",
>       "guide_url": "https://rocketvalidator.com/accessibility-validation/axe/4.8/aria-valid-attr",
>       "help": "ARIA attributes must conform to valid names",
>       "help_url": "https://dequeuniversity.com/rules/axe/4.8/aria-valid-attr",
>       "html": [
>         "<svg class=\"d-block mx-1\" title=\"Windows\" aria-title=\"Windows\" width=\"18\" height=\"18\" viewBox=\"0 0 24 24\" xmlns=\"http://www.w3.org/2000/svg\" fill-rule=\"evenodd\" clip-rule=\"evenodd\" fill=\"currentColor\">",
>         "<svg class=\"d-block mx-1\" title=\"Linux\" aria-title=\"Linux\" width=\"18\" height=\"18\" viewBox=\"0 0 24 24\" xmlns=\"http://www.w3.org/2000/svg\" fill-rule=\"evenodd\" clip-rule=\"evenodd\" fill=\"currentColor\">",
>         "<svg class=\"d-block mx-1\" title=\"Web\" aria-title=\"Web\" width=\"18\" height=\"18\" viewBox=\"0 0 24 24\" xmlns=\"http://www.w3.org/2000/svg\" fill-rule=\"evenodd\" clip-rule=\"evenodd\" fill=\"currentColor\">",
>         "<svg class=\"d-block mx-1\" title=\"macOS\" aria-title=\"macOS\" width=\"18\" height=\"18\" viewBox=\"0 0 24 24\" xmlns=\"http://www.w3.org/2000/svg\" fill-rule=\"evenodd\" clip-rule=\"evenodd\" fill=\"currentColor\">"
>       ],
>       "impact": "critical",
>       "impact_order": 4,
>       "inserted_at": "2024-03-05T12:45:14",
>       "tags": [
>         "cat.aria",
>         "wcag2a",
>         "wcag412",
>         "EN-301-549",
>         "EN-9.4.1.2"
>       ],
>       "updated_at": "2024-03-05T12:45:14",
>       "url": "https://github.blog/2024-02-29-game-bytes-february-2024/"
>     },
>     "id": "26218481",
>     "relationships": {
>       "report": {
>         "links": {
>           "related": "https://rocketvalidator.com/api/v1/reports/72eecced-8472-41fc-b194-59b7496c7576"
>         }
>       },
>       "web_page": {
>         "links": {
>           "related": "https://rocketvalidator.com/api/v1/reports/72eecced-8472-41fc-b194-59b7496c7576/web_pages/8413311"
>         }
>       }
>     },
>     "type": "a11y_issue"
>   },
>   "jsonapi": {
>     "version": "1.0"
>   }
> }
> ```

## List Accessibility issues on a web page

To list the accessibility issues found on a web page, send a `GET` request to `/api/v1/reports/$REPORT_ID/web_pages/$WEBPAGE_ID/a11y_issues`.


> **Example: list A11Y issues for a web page**
>
> ```
> GET /api/v1/reports/$REPORT_ID/web_pages/$WEB_PAGE_ID/a11y_issues
> ```

### Filtering by help

To include only the accessibility issues of a given kind, use the `filter[help]` option.


> **Example: filter A11Y issues for a web page about "landmark"**
>
> ```
> GET /api/v1/reports/$REPORT_ID/web_pages/$WEB_PAGE_ID/a11y_issues?filter[help]=landmark
> ```

### Filtering by tag

To include only the issues for a given `tags` combination, use the `filter[tags]` options:

* `filter[tags][mode]` setting the tag combination mode, which can be `any`, `all` or `none`.
* `filter[tags][list]` including a comma-separated list of tags.


> **Example: filter A11Y issues for a web page tagged with "wcag2a"**
>
> ```
> GET /api/v1/reports/$REPORT_ID/web_pages/$WEB_PAGE_ID/a11y_issues?filter[tags][mode]=any&filter[tags][list]=wcag2a
> ```

## Retrieve an Accessibility issue

To show an individual Accessibility issue on a web page, send a `GET` request to `/api/v1/reports/$REPORT_ID/web_pages/$WEB_PAGE_ID/a11y_issues/$A11Y_ISSUE_ID`


> **Example: retrieve A11Y issue for a web page**
>
> ```
> GET `/api/v1/reports/$REPORT_ID/web_pages/$WEBPAGE_ID/a11y_issues/$A11Y_ISSUE_ID
> ```