# Common AccessLint Issues

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

Typically, the same kind of issue affects many Web Pages on a given Report. For example, the issue <code>"Image element is missing an alt attribute."</code> may affect many Web Pages on the same report.

A Common AccessLint Issue represents a given <a href="https://rocketvalidator.com/docs/api-v2/accesslint_issues">AccessLint Issue</a> that is common to many Web Pages, thus showing its details, how many times it's found on the Report, and links to the related Web Pages. All findings for the same canonical rule belong to one Common AccessLint Issue, even when their original messages differ.

## Attributes

<dl>
  <dt>ID</dt>
  <dd>Stable canonical rule ID, including its slash, such as <code>distinguishable/color-contrast</code>. It remains the same after rechecking the report.</dd>

  <dt>Report ID</dt>
  <dd>ID of the report.</dd>

  <dt>Rule ID</dt>
  <dd>ID of the AccessLint Core rule that reports this issue, such as <code>text-alternatives/img-alt</code>. This is also the public issue ID.</dd>

  <dt>Message</dt>
  <dd>AccessLint's heading for the rule, such as <code>Images must have alternate text</code>, or the rule ID when Rocket Validator has no guide for it. Original engine messages remain on each element.</dd>

  <dt>How Many</dt>
  <dd>Total times this issue has been found in the web pages for the report.</dd>

  <dt>Impact</dt>
  <dd>Highest severity among the findings in this group.</dd>

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

  <dt>Description</dt>
  <dd>Short plain-text explanation of the issue, from the Rocket Validator guide for its rule. Null when no guide matches. This is Rocket Validator's own explanation, and is separate from the Message attribute, which carries the rule heading.</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**
>
> When no guide matches an issue, the four description and guide attributes are
> `null`. Treat them as optional.

## Relationships

<dl>
  <dt>Web Pages</dt>
  <dd>The list of Web Pages affected by this issue.</dd>
</dl>

## Example


> **Example: Common AccessLint Issue**
>
> ```json
> {
>   "data": {
>     "attributes": {
>       "description": "Images must have alternate text. Add an alt attribute to <img> elements. Decorative images may use an empty alt attribute (alt=\"\"), role='none', or role='presentation'.",
>       "description_html": "<p>Images must have alternate text. Add an alt attribute to <code>&lt;img&gt;</code> elements. Decorative images may use an empty alt attribute (alt=&quot;&quot;), role='none', or role='presentation'.</p>",
>       "description_markdown": "Images must have alternate text. Add an alt attribute to `<img>` elements. Decorative images may use an empty alt attribute (alt=\"\"), role='none', or role='presentation'.",
>       "guide_url": "https://rocketvalidator.com/accessibility-validation/accesslint/0.21/text-alternatives/img-alt",
>       "how_many": 9,
>       "impact": "critical",
>       "impact_order": 4,
>       "message": "Images must have alternate text",
>       "report_id": "2455a63a-7e16-4cbf-8455-6c9a88195142",
>       "rule_id": "text-alternatives/img-alt"
>     },
>     "id": "text-alternatives/img-alt",
>     "relationships": {
>       "web_pages": {
>         "links": {
>           "related": "https://rocketvalidator.com/api/v2/reports/2455a63a-7e16-4cbf-8455-6c9a88195142/web_pages?filter[common_accesslint_issue_id]=text-alternatives/img-alt"
>         }
>       }
>     },
>     "type": "common_accesslint_issue"
>   },
>   "jsonapi": {
>     "version": "1.0"
>   }
> }
> ```

## List Common AccessLint Issues on a Report

To list the Common AccessLint issues found on a report, send a `GET` request to `/api/v2/reports/$REPORT_ID/common_accesslint_issues`.


> **Example: list the Common AccessLint issues found on a report**
>
> ```
> GET /api/v2/reports/$REPORT_ID/common_accesslint_issues
> ```

### Filtering by message

To include only the AccessLint issues of a given kind, use the `filter[message]` option. It matches part of the rule heading that the issue returns as `message`, an original element message or the canonical rule ID, ignoring case. A match selects the complete rule group, including findings with other messages.


> **Example: filter AccessLint issues for a report about "contrast"**
>
> ```
> GET /api/v2/reports/$REPORT_ID/common_accesslint_issues?filter[message]=contrast
> ```

AccessLint Core doesn't tag its results, so you can't filter Common AccessLint issues by tag.

## List Common AccessLint Issues by Category

To list every rule group in a category, send a `GET` request to `/api/v2/reports/$REPORT_ID/common_accesslint_issues/$CATEGORY`. The category is the part of the canonical rule ID before its slash, such as `distinguishable` in `distinguishable/color-contrast`.

> **Example: list Common AccessLint issues by category**
>
> ```
> GET /api/v2/reports/$REPORT_ID/common_accesslint_issues/$CATEGORY
> ```

Category matching is exact and case-sensitive. Categories use lowercase letters, digits and hyphens, beginning with a letter. A valid category with no findings returns `200 OK` with an empty collection (`"data": []`). Invalid categories and inaccessible reports return `404 Not Found`.

The response uses the same rule groups and [pagination](https://rocketvalidator.com/docs/api-v2/pagination) as the full issue list. You can combine the category with `filter[message]`; matching groups still include all their findings.

> **Example: paginate matching issues in the distinguishable category**
>
> ```
> GET /api/v2/reports/$REPORT_ID/common_accesslint_issues/distinguishable?filter[message]=contrast&page[number]=1&page[size]=25
> ```

## Retrieve a Common AccessLint Issue

To retrieve a Common AccessLint Issue on a given Report, send a GET request to `/api/v2/reports/$REPORT_ID/common_accesslint_issues/$CATEGORY/$RULE_SLUG`.


> **Example: retrieve a Common AccessLint issue on a report**
>
> ```
> GET /api/v2/reports/$REPORT_ID/common_accesslint_issues/$CATEGORY/$RULE_SLUG
> ```

The ID `distinguishable/color-contrast` uses the detail path `/common_accesslint_issues/distinguishable/color-contrast`. Keep the slash as a path separator.

## List the Web Pages affected by a Common AccessLint Issue

To list the Web Pages that are affected by a given issue, refer to <a href="https://rocketvalidator.com/docs/api-v2/web_pages#filtering-by-accesslint-issue">Filtering by AccessLint issue</a> on the Web pages endpoint.