Issue descriptions and guide links are now in the API

Until now, the Rocket Validator API told you what was wrong with a page, but not what to do about it. An issue came back with its message, its location and its tags, and the explanation of how to fix it lived only in the web interface. If you were building a dashboard, filing tickets automatically or feeding results into another tool, you had to write that context yourself.

That gap is closed. Every issue returned by the API now includes a short description of the problem and a link to its full guide.

Four new attributes

Four attributes were added to each issue:

• description is the explanation as plain text, ready for a terminal, a commit message or a Jira ticket.
• description_markdown is the same text in markdown, with inline code and emphasis preserved.
• description_html is the same text already rendered as HTML, ready to drop into a page.
• guide_url is the absolute URL of the full guide on rocketvalidator.com.

Three formats of the same text may look redundant, but each one has a different destination. Markdown is what you want in a pull request comment. HTML is what you want in a report you are generating. Plain text is what you want when the destination cannot render either.

An HTML validation issue

Here is a request for the common HTML issues of a report:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Accept: application/vnd.api+json" \
     "https://rocketvalidator.com/api/v1/reports/12345/common_html_issues"

And here is one of the issues it returns, showing the new attributes:

{
  "id": "67890",
  "type": "common_html_issue",
  "attributes": {
    "message": "Duplicate attribute “class”.",
    "issue_type": "error",
    "how_many": 14,
    "tags": ["duplicate attribute"],
    "description": "Each HTML element must have unique attribute names — no attribute can appear more than once on the same element. When the W3C validator reports \"Duplicate attribute,\" it means an attribute like id, class, or any other has been specified two or more times on a single element. To fix this, merge the duplicate attributes into a single declaration or remove the unintended repetition.",
    "description_markdown": "Each HTML element must have unique attribute names — no attribute can appear more than once on the same element. When the W3C validator reports \"Duplicate attribute,\" it means an attribute like `id`, `class`, or any other has been specified two or more times on a single element. To fix this, merge the duplicate attributes into a single declaration or remove the unintended repetition.",
    "description_html": "<p>Each HTML element must have unique attribute names — no attribute can appear more than once on the same element. When the W3C validator reports \"Duplicate attribute,\" it means an attribute like <code>id</code>, <code>class</code>, or any other has been specified two or more times on a single element. To fix this, merge the duplicate attributes into a single declaration or remove the unintended repetition.</p>",
    "guide_url": "https://rocketvalidator.com/html-validation/duplicate-attribute-x"
  }
}

Notice the difference between the three formats. The markdown version keeps `id` and `class` as inline code, the HTML version renders them as <code> elements, and the plain text version drops the markup entirely so the sentence reads cleanly anywhere.

An accessibility issue

The same four attributes are available on accessibility issues. Here is an abridged response, showing description and guide_url:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Accept: application/vnd.api+json" \
     "https://rocketvalidator.com/api/v1/reports/12345/web_pages/54321/a11y_issues"

{
  "id": "24680",
  "type": "a11y_issue",
  "attributes": {
    "impact": "critical",
    "help": "Images must have alternative text",
    "help_url": "https://dequeuniversity.com/rules/axe/4.12/image-alt",
    "tags": ["WCAG 2.1 (A)", "WCAG 2.0 (A)", "Section 508", "blind"],
    "description": "Every <img> element must have alternative text so that screen readers can convey the image's meaning to users who cannot see it. You can provide alternative text using the alt attribute, aria-label, or aria-labelledby. Decorative images that convey no information should use an empty alt attribute (alt=\"\") to tell assistive technology to skip them.",
    "guide_url": "https://rocketvalidator.com/accessibility-validation/axe/4.12/image-alt"
  }
}

Accessibility issues already carried help and help_url, which come from the checking engine and point at Deque University. Those attributes are unchanged. The new description and guide_url augment them with the Rocket Validator guide for the same rule, matched against the ruleset that produced the check. You get both references and can use whichever fits your workflow.

Building something with it

Because the description travels with the issue, a useful summary is now a single request. This example fetches the common accessibility issues of a report and prints a fix list:

const token = process.env.ROCKET_VALIDATOR_TOKEN;
const reportId = 12345;

const response = await fetch(
  `https://rocketvalidator.com/api/v1/reports/${reportId}/common_a11y_issues`,
  {
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/vnd.api+json",
    },
  }
);

const { data } = await response.json();

for (const issue of data) {
  const { help, how_many, description, guide_url } = issue.attributes;

  console.log(`${help} (${how_many} occurrences)`);

  if (description) {
    console.log(`  ${description}`);
    console.log(`  Guide: ${guide_url}`);
  }
}

The same payload works just as well for rendering. If you are generating an HTML report, use description_html directly instead of converting the text yourself.

When the guide is missing

The four attributes are nullable, and that is worth designing for. Guides cover the issues that come up most often, but the W3C validator can produce a very long tail of messages, and there is no guide for every single one. When no guide matches an issue, all four attributes come back as null. This is a normal outcome, not an error.

So fall back to the data that is always there:

const { message, description, guide_url } = issue.attributes;

const explanation = description ?? message;
const link = guide_url ?? null;

An issue always has its message (for HTML issues) or its help and help_url (for accessibility issues), so there is always something to show.

Where you get them

The new attributes are included in the four issue endpoints:

• GET /api/v1/reports/:report_id/web_pages/:web_page_id/html_issues
• GET /api/v1/reports/:report_id/web_pages/:web_page_id/a11y_issues
• GET /api/v1/reports/:report_id/common_html_issues
• GET /api/v1/reports/:report_id/common_a11y_issues

There is nothing to enable and no extra parameter to pass. The attributes are already in the responses, and since this is an addition to the payload, existing integrations keep working unchanged.

Have a look at the API documentation to get started, and tell us what you build with it.