Validates a spec-compliant ARD ai-catalog.json for agent discovery
3 of 3 free audits left today
See what AI Catalog finds on your site. No sign-up needed.
The auditor resolves the site origin from the audited URL and locates ai-catalog.json:
Well-known URI — GET {origin}/.well-known/ai-catalog.json.
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.
HTML fallback — otherwise look for <link rel="ai-catalog" href="..."> on the audited page.
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.
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.
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.
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.
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.
| CheckCode | Status | When it fires | Recommendation | Why it matters |
|---|---|---|---|---|
37A-AiCatalogAuditor-100 | INFORMATION | Every run. Records that this auditor implements ARD v0.91 and the pinned ai-catalog.schema.json commit. | This auditor implements ARD v0.91; catalog documents still use specVersion "1.0". Schema pin 4a8a6b8fdd3ac4a50dcb63213573159c1eed7856. | — |
37A-AiCatalogAuditor-400 | FAIL | The catalog HTTP response has a missing or blank Content-Type header. | Send Content-Type: application/json for {catalogUrl}. | Without a Content-Type, agents and registries cannot tell the catalog is JSON and many skip it, so the capabilities it lists stay undiscovered. |
37A-AiCatalogAuditor-401 | FAIL | Content-Type is present but is not application/json or a +json type. | Serve {catalogUrl} as application/json instead of {contentType}. | Crawlers that check the media type before parsing treat a non-JSON catalog as a stray page and move on, so the site's capabilities are never indexed. |
37A-AiCatalogAuditor-402 | FAIL | specVersion is missing or is not "1.0". | Set specVersion to "1.0" on {catalogUrl}; current value is {observed}. | Registries use specVersion to pick a parser; an unknown or missing version makes them reject the whole catalog, so none of its entries are indexed. |
37A-AiCatalogAuditor-403 | FAIL | entries is missing or is not an array. | Add an entries array on {catalogUrl} listing the advertised agentic resources. | The entries array is the catalog's content; without it registries have nothing to index, so the site's agents and tools stay invisible to AI discovery. |
37A-AiCatalogAuditor-404 | FAIL | host is present but host.displayName is missing or blank. | Set host.displayName on {catalogUrl} to a human-readable publisher name. | The host name is how registries and agents show who publishes the catalog; without it the listing is anonymous and schema-strict consumers reject the file. |
37A-AiCatalogAuditor-405 | FAIL | A catalog entry has no identifier. | Set identifier on entry {label} in {catalogUrl} to a urn:air:<publisher>:<namespace>:<agent-name> URN. | An entry without an identifier cannot be indexed, deduplicated or trusted by registries, so the capability it describes is dropped from discovery. |
37A-AiCatalogAuditor-406 | FAIL | A catalog entry has no displayName. | Set displayName on entry {label} in {catalogUrl}. | The display name is what agents and people see when the entry shows up in search; without it the capability is unnamed and schema-strict consumers drop it. |
37A-AiCatalogAuditor-407 | FAIL | A catalog entry has no type. | Set type on entry {label} in {catalogUrl} to an IANA media type such as application/mcp-server-card+json. | The type tells an agent how to use the entry (MCP server, A2A agent, nested catalog); without it the entry cannot be consumed and is skipped. |
37A-AiCatalogAuditor-408 | FAIL | An entry identifier is present but does not match urn:air:<publisher>:<namespace>:<agent-name>. | Change {identifier} in {catalogUrl} to a domain-anchored URN such as urn:air:example.com:agent:assistant. | Registries rely on domain-anchored urn:air identifiers to keep entries unique and bind them to the publisher; an identifier in any other form breaks federation and is rejected. |
37A-AiCatalogAuditor-409 | FAIL | An entry has both url and data. | Keep only url or only data on entry {label} in {catalogUrl}; the schema forbids both. | Consumers cannot tell whether to fetch the resource or read the inline payload, so schema-strict parsers reject the entry and the capability goes unlisted. |
37A-AiCatalogAuditor-410 | FAIL | An entry has neither url nor data. | Add url or inline data on entry {label} in {catalogUrl}. | An entry with no url and no data points to nothing, so agents have no way to reach the capability and registries drop it. |
37A-AiCatalogAuditor-411 | FAIL | A trustManifest object is present without identity. | Set trustManifest.identity on {label} in {catalogUrl} to a SPIFFE ID, DID, or HTTPS FQDN URI. | A trust manifest without an identity cannot prove who stands behind the resource, so the trust signals it carries are ignored and cautious agents will not connect. |
37A-AiCatalogAuditor-412 | FAIL | An attestation object has no type. | Set attestation.type on {label} in {catalogUrl} (e.g. SOC2-Type2). | Without a type, agents cannot tell what the attestation certifies, so it adds no trust and schema-strict consumers reject it. |
37A-AiCatalogAuditor-413 | FAIL | An attestation object has no uri. | Set attestation.uri on {label} in {catalogUrl} to the attestation document URL. | Without a uri the attestation cannot be verified, so it adds no trust and schema-strict consumers reject it. |
37A-AiCatalogAuditor-414 | FAIL | An attestation object has no mediaType. | Set attestation.mediaType on {label} in {catalogUrl} (e.g. application/pdf). | Without a media type agents cannot read the attestation document, so it cannot be verified and schema-strict consumers reject it. |
37A-AiCatalogAuditor-415 | FAIL | No catalog was found at /.well-known/ai-catalog.json, robots.txt Agentmap:, or <link rel="ai-catalog">. | Publish ai-catalog.json at /.well-known/ai-catalog.json for {url}, or advertise it with an Agentmap: robots.txt directive or <link rel="ai-catalog">. | Without a catalog, AI agents and registries have no standard way to discover the site's MCP servers, agents and other capabilities, so they go unlisted and unused. |
37A-AiCatalogAuditor-416 | FAIL | A catalog was found but the body is not valid JSON. | Fix the JSON served for {url}; parser reported {detail}. | A catalog that does not parse is the same as no catalog: agents and registries discard it, so none of the site's capabilities are discovered. |
37A-AiCatalogAuditor-300 | WARNING | The catalog response has no Access-Control-Allow-Origin header. | Add Access-Control-Allow-Origin: * on {catalogUrl} so discovery crawlers can fetch the catalog. | Browser-based agents and crawlers cannot read a catalog that lacks CORS headers, so for them the catalog is effectively unpublished. |
37A-AiCatalogAuditor-301 | WARNING | entries is an empty array. | Add at least one catalog entry on {catalogUrl} so agents can discover capabilities. | An empty catalog advertises nothing, so publishing it brings no discovery: agents find the file and move on. |
37A-AiCatalogAuditor-302 | WARNING | The root host object is omitted. | Add a host object with displayName on {catalogUrl} so publishers can be identified. | Without a host, registries cannot say who publishes the catalog, which makes the listing anonymous and less trusted by agents choosing where to connect. |
37A-AiCatalogAuditor-303 | WARNING | representativeQueries is present but does not contain 2–5 strings. | Change representativeQueries on {label} in {catalogUrl} from size {observed} to 2–5 examples. | Registries build search embeddings from these example queries; too few give the entry weak search ranking and too many get it rejected by schema-strict consumers. |
37A-AiCatalogAuditor-304 | WARNING | updatedAt is present but is not an ISO 8601 date-time. | Set updatedAt on {label} in {catalogUrl} to an ISO 8601 timestamp such as 2026-01-15T12:00:00Z instead of {observed}. | Registries use updatedAt to decide when to re-crawl and which version is newest; an unreadable date leaves the entry stale or rejected. |
37A-AiCatalogAuditor-500 | ERROR | The audited URL is null or blank. | Pass a non-blank page URL instead of {observed} so the auditor can discover ai-catalog.json. | — |
37A-AiCatalogAuditor-501 | ERROR | The audited URL is not a valid URI. | Pass an absolute HTTP(S) URL instead of {url}; parser reported {detail}. | — |
37A-AiCatalogAuditor-502 | ERROR | Discovery failed with an unexpected exception. | Retry the audit of {url}; the auditor failed with {detail}. | — |
37A-AiCatalogAuditor-200 | SUCCESS | Every rule above passed; one SUCCESS check is added with the message AI catalog at "{catalogUrl}" is valid: specVersion {specVersion}, {entryCount} entries. | — | — |
| Status | Description | Test logic |
|---|---|---|
| INFORMATION | Provenance only; does not change overall status | Every run includes 37A-AiCatalogAuditor-100 with ARD v0.91 and schema commit 4a8a6b8f… in the message and Check.data. |
| SUCCESS | A catalog was found and every publishing and schema rule passed | Well-known, Agentmap, or HTML rel="ai-catalog" returned parseable JSON; Content-Type is JSON; specVersion is 1.0; entries is a non-empty array; each entry has a valid urn:air identifier, displayName, type, and exactly one of url or data; CORS is present. The specification pin check is still present. |
| WARNING | The catalog is usable but incomplete for crawlers or search | Missing Access-Control-Allow-Origin (300); empty entries (301); omitted host (302); representativeQueries not sized 2–5 (303); or updatedAt not ISO 8601 (304). No FAIL rule fired. The specification pin check is still present. |
| FAIL | The catalog is missing, not JSON, or violates a schema MUST | Not found at well-known / Agentmap / HTML link (415); unparseable JSON (416); missing or non-JSON Content-Type (400, 401); specVersion not 1.0 (402); no entries array (403); host.displayName missing (404); missing entry fields (405–407); invalid URN (408); both or neither url/data (409, 410); trustManifest without identity (411); incomplete attestations (412–414). The specification pin check is still present. |
| ERROR | The request cannot be audited | The audited URL is null or blank (500), not a valid URI (501), or discovery threw (502). Checks include the specification pin (100) and the process error. |
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.
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.
This documentation is built and hosted on Mintlify, a developer documentation platform.
Add this auditor to your monitoring setup and start identifying issues on your websites today.