A complete ai-catalog.json example, explained

Last reviewed 2026-07-06 · Agent Ardvark field notes

Below is a complete, valid ai-catalog.json under version 1.0 of the ARD specification. Copy it, replace the example values with your own, and host it at /.well-known/ai-catalog.json. Or skip the hand-editing and use our free generator, which produces a spec-valid file from a plain-English form.

{
  "specVersion": "1.0",
  "host": { "displayName": "Example Studio" },
  "entries": [
    {
      "identifier": "urn:air:example.com:api:bookings",
      "displayName": "Booking API",
      "type": "application/openapi+json",
      "url": "https://example.com/openapi.json",
      "description": "Check availability and book appointments.",
      "representativeQueries": [
        "book a session at Example Studio",
        "what slots are free on Friday"
      ]
    }
  ]
}

Field by field

specVersion — must be exactly the string "1.0". Anything else fails validation.

host — optional but recommended. Names the publisher. displayName is required if the block is present; you can also add documentationUrl and logoUrl.

entries — the list of things you are advertising. Each entry:

• identifier — a URN in the form urn:air:<your-domain>:<namespace>:<name>. It must match the spec's pattern; lowercase letters, digits, dots and hyphens are safe.
• displayName — a human-readable title.
• type — an IANA media type saying what kind of resource this is. Common ones: application/mcp-server-card+json for an MCP server, application/a2a-agent-card+json for an A2A agent, application/openapi+json for an API.
• url or data — exactly one of the two. url points at the resource's own description file; data embeds it inline. Both together is invalid, and so is neither.
• representativeQueries — optional, 2 to 5 natural-language questions your resource answers. Strongly recommended: agent registries use them for semantic matching, so they act like keywords.

The three mistakes that fail validation most

First, a malformed identifier (missing the urn:air: prefix or using illegal characters). Second, including both url and data in one entry. Third, a specVersion that is not exactly "1.0". Our checker catches all three and tells you what to fix.

Frequently asked questions

Can I have more than one entry?

Yes, as many as you like. Each needs its own unique identifier. An empty entries array is technically valid but advertises nothing.

What media type do I use for a plain website?

The spec is designed around machine-usable resources (APIs, MCP servers, agents). For plain content sites, listing an API or feed is most useful; check the spec for evolving guidance.