Skip to content

Example: Minimal Catalog

The simplest valid AI Catalog — just a specVersion and a list of entries. This is Level 1 (Minimal) conformance.

{
  "specVersion": "1.0",
  "entries": [
    {
      "identifier": "urn:air:example.com:skill:code-review",
      "displayName": "Code Review Assistant",
      "type": "application/agent-skills+zip",
      "url": "https://skills.example.com/code-review/skill.zip"
    },
    {
      "identifier": "urn:air:example.com:mcp:weather",
      "type": "application/mcp-server-card+json",
      "url": "https://api.example.com/mcp/server-card"
    },
    {
      "identifier": "urn:air:example.com:a2a:research",
      "type": "application/a2a-agent-card+json",
      "url": "https://agents.example.com/researchAssistant"
    }
  ]
}

Breakdown

specVersion: "1.0" Identifies the version of the AI Catalog specification this document conforms to. Always present. Clients check this before processing.

entries The list of artifacts. Each entry requires identifier, type, and url (or data).

identifier A stable, unique string for this artifact. The recommended format is urn:air:{domain}:{namespace}:{name}. The identifier should not change when the artifact moves or is versioned.

type What kind of artifact this is. Clients use this to decide whether they can use the artifact — without fetching it.

displayName Optional. Notice that the MCP server and A2A agent entries omit displayName — those artifact formats carry their own canonical names (title and name respectively). The skill bundle entry sets displayName because ZIP archives don't embed a self-describing name.

url Where to fetch the full artifact document.

Upgrading to Level 2

Add a host object to identify your organization and officially reach Level 2 (Discoverable):

{
  "specVersion": "1.0",
  "host": {
    "displayName": "Example Corp",
    "identifier": "did:web:example.com"
  },
  "entries": [...]
}

Then serve the catalog at /.well-known/ai-catalog.json to enable automated domain-level discovery.