# AI Catalog (ai-catalog.json) The AI Catalog is the static JSON file a publisher hosts to advertise its AI capabilities. It's the unit of publication in the [[Agentic Resource Discovery Specification (ARD)|ARD]] world: the thing publishers write, and the thing registries crawl. Think of it as a sitemap, but for agentic resources instead of web pages. The canonical location is a well-known path on the publisher's domain: ``` https://<publisher-domain>/.well-known/ai-catalog.json ``` It must be served over HTTPS, with `Content-Type: application/json` and `Access-Control-Allow-Origin: *`. Its own media type is `application/ai-catalog+json`. ## Structure At the top level the file is small: - **`specVersion`** (required) — the format version, currently `"1.0"`. Minor bumps are backward-compatible; consumers must ignore fields they don't recognize. - **`entries`** (required) — the array of catalog entries. It can be empty, but it must be present. - **`host`** (optional) — a Host Info object naming the operator of the catalog itself (display name, optional verifiable identifier like `did:web:acme.com`, logo, docs). ## Catalog entries Each entry in `entries` describes one artifact. The required fields: - **`identifier`** — a domain-anchored URN (see [[ARD URN Identifier]]), e.g. `urn:air:acme.com:agent:assistant`. - **`displayName`** — a human-readable name. - **`type`** — an IANA media type saying what kind of artifact it is. Then exactly **one** of (this is enforced, mutually exclusive): - **`url`** — where to fetch the full artifact document, or - **`data`** — the full artifact document inline. Useful optional fields make the entry searchable without fetching the artifact: `description`, `tags`, `capabilities` (explicit skill names for fast database filtering), `representativeQueries` (2 to 5 natural-language example queries a registry turns into search embeddings), `version`, `updatedAt`, and a `trustManifest` (see [[ARD Trust Manifest]]). ## What can be listed The `type` field is the key to ARD being artifact-agnostic. Anything gets an entry as long as it has a media type. Common ones: - `application/mcp-server-card+json` — an [[Model Context Protocol (MCP)|MCP]] server card - `application/a2a-agent-card+json` — an Agent2Agent (A2A) agent card - `application/ai-registry+json` — an [[Agent Registry (ARD)|Agent Registry]] (so catalogs point to dynamic search services) - `application/ai-catalog+json` — a nested catalog (for org hierarchies or bundles) - `application/ai-skill` — an AI Skill ## Conformance levels The upstream `ai-catalog` standard defines three levels you can target: **Minimal** (just `specVersion` + `entries`), **Discoverable** (adds the `host` object), and **Trusted** (adds trust manifests and verifiable publisher identity). You start simple and layer in trust later, which is the right default. ## References - https://agenticresourcediscovery.org/ai_catalog_spec/ - https://agenticresourcediscovery.org/how_to_publish/ - https://github.com/ards-project/ard-spec ## Related - [[Agentic Resource Discovery Specification (ARD)]] - [[ARD URN Identifier]] - [[ARD Discovery Mechanisms]] - [[Agent Registry (ARD)]] - [[ARD Trust Manifest]] - [[Model Context Protocol (MCP)]]