API V2 reference (beta)

Common AccessLint Issues

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

A Common AccessLint Issue represents a given AccessLint Issue 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

ID: Stable canonical rule ID, including its slash, such as distinguishable/color-contrast. It remains the same after rechecking the report.
Report ID: ID of the report.
Rule ID: ID of the AccessLint Core rule that reports this issue, such as text-alternatives/img-alt. This is also the public issue ID.
Message: AccessLint's heading for the rule, such as Images must have alternate text, or the rule ID when Rocket Validator has no guide for it. Original engine messages remain on each element.
How Many: Total times this issue has been found in the web pages for the report.
Impact: Highest severity among the findings in this group.
Impact Order: Numerical representation of the Impact.
Description: 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.
Description Markdown: The same explanation in Markdown. Null when no guide matches.
Description HTML: The same explanation as rendered HTML. Null when no guide matches.
Guide URL: Link to the full guide for this issue. Null when no guide matches.

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

Web Pages: The list of Web Pages affected by this issue.

Example

Example: Common AccessLint Issue

{
  "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 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 Filtering by AccessLint issue on the Web pages endpoint.