Skip to main content
AI Readiness Auditor — validates that the site publishes a spec-compliant ARD ai-catalog.json so agents can discover MCP servers, A2A agents, and other capabilities.

AI Readiness

Agents and registries can find the site’s capabilities from a well-known catalog instead of hard-coded installs.

Interoperability

Entries follow the AI Catalog envelope: domain-anchored URNs, media types, and strict url-or-data content.
The Agentic Resource Discovery specification defines how publishers advertise agentic resources in a static ai-catalog.json manifest. Registries crawl that file from a well-known URL (or from robots.txt / HTML hints) and index identifier, type, capabilities, and representativeQueries for search. This auditor discovers the catalog for the audited origin and checks publishing headers plus the AI Catalog JSON Schema MUST/SHOULD rules.

​
How it works

The auditor resolves the site origin from the audited URL and locates ai-catalog.json:
  1. Well-known URI — GET {origin}/.well-known/ai-catalog.json.
  2. Agentmap fallback — if the well-known path is missing or returns non-JSON (for example an HTML catch-all), parse /robots.txt for an Agentmap: directive.
  3. HTML fallback — otherwise look for <link rel="ai-catalog" href="..."> on the audited page.
  4. Header checks — the catalog response should be JSON (Content-Type: application/json or a +json type) with Access-Control-Allow-Origin so crawlers can fetch it.
  5. Schema checks — specVersion must be 1.0; entries must be an array; each entry needs identifier, displayName, type, and exactly one of url or data; identifiers must match urn:air:<publisher>:<namespace>:<agent-name>. Nested application/ai-catalog+json data objects are checked one level deep with the same entry rules.
  6. Specification pin — every run emits 37A-AiCatalogAuditor-100 (INFORMATION) naming ARD v0.91 (26 Aug 2026) and ai-catalog.schema.json commit 4a8a6b8fdd3ac4a50dcb63213573159c1eed7856 (20 Jun 2026). That check does not change overall status.
  7. Aggregate — any failing rule makes the audit FAIL; otherwise warnings (CORS, empty entries, omitted host, representativeQueries size, invalid updatedAt) make it WARNING; otherwise SUCCESS.
A missing catalog or a JSON parse error produces a FAIL and still includes the specification pin check.

​
What it audits

Every row maps to one checkRule* method and one CheckCode. Nested inline catalogs reuse the same entry rules (402–414, 301, 303–304); hosting rules (400, 401, 300) and host object rules (404, 302) apply only to the HTTP catalog response. 37A-AiCatalogAuditor-100 is emitted on every run, including missing-catalog and invalid-JSON failures. CheckCode suffixes use status ranges: 100 information, 200 success, 300–399 warning, 400–499 fail, 500–599 error.

​
Output documentation

​
Risks and considerations

​
Discovery

  • Agents and federated registries look first at /.well-known/ai-catalog.json. An HTML SPA that serves 200 for every path hides the catalog unless Content-Type is JSON or an Agentmap / HTML link points at the real file.
  • CORS (Access-Control-Allow-Origin: *) is required for browser-based crawlers. A catalog that exists but cannot be read cross-origin is effectively unpublished.

​
Schema fidelity

  • Identifiers must stay urn:air: domain-anchored names. HTTP URLs in identifier break federation uniqueness and trust binding described in the ARD specification.
  • Strict value-or-reference (url XOR data) keeps parsers from choosing between two payloads. Both or neither makes the entry unusable.
  • representativeQueries (2–5 examples) are how registries build semantic embeddings. Omitting them is allowed; a list of the wrong size is a warning because search ranking will be weak or rejected by schema-strict consumers.