ai-catalog.json: Resource Discovery for AI
Author: Domeny.ForSale editorial team Published Updated
In brief: /.well-known/ai-catalog.json is an earlier path for publishing a resource manifest for AI agents, described as the predecessor to /.well-known/ard.json in the Agentic Resource Discovery (ARD) specification. This kind of manifest describes available tools, agents or instructions for using them in a structured JSON format. New implementations should use the ard.json path and an HTML link with rel="ard".
This article is based on the ARD v0.91 specification , dated 26 August 2026 and marked as a Proposal. The documentation was checked on 3 October 2026.
What is a resource catalog for agents used for?
An assistant that needs an external tool must first establish what the tool does and where to find its description. A manifest lets the publisher present this information in a shared structure. Individual entries can point to, among other things, an MCP server description, an A2A agent card or a file containing instructions for performing a task, known as a skill.
In ARD, publishing a manifest is the static part of resource discovery. A registry has a separate role: it retrieves entries, indexes them and provides search. This allows a client to submit a query describing a specific need and receive matching resources. The JSON file itself does not execute tools; the relevant protocol or instructions define how to run them. These layers are described in sections 3 and 5 of the specification .
Why is ard.json used now?
In section 5.1 , the specification sets out clear rules for discovering manifests:
| Mechanism | Current name | Earlier name |
|---|---|---|
| File on the domain | /.well-known/ard.json | /.well-known/ai-catalog.json |
| Link in HTML | rel="ard" | rel="ai-catalog" |
| Support by an ARD client | Required when discovering domain entries | Optional backward compatibility |
A specification-compliant client discovering a domain’s resources must fetch /.well-known/ard.json and honor the rel="ard" link. It may also check the earlier path and the ai-catalog relation; if it does, it treats them as equivalent sources of entries.
This means that a site providing only ai-catalog.json may be missed by a correctly functioning ARD client. The specification recommends switching to ard.json. Keeping the old address alongside the new one remains an option for older integrations, not a requirement for a new implementation.
What does a valid manifest look like?
The document contains an entries array with descriptions of individual resources. The example below is an abridged version of the
Domeny.ForSale manifest
:
{
"entries": [
{
"identifier": "urn:air:domeny.forsale:skill:domain-catalog-search",
"displayName": "Domeny.ForSale catalog search",
"type": "text/markdown; profile=\"urn:air:agent-skills\"",
"url": "https://domeny.forsale/.well-known/agent-skills/domain-catalog-search/SKILL.md",
"capabilities": ["searchDomainCatalog"],
"representativeQueries": [
"find a domain for sale for an online store",
"show articles about choosing and buying a domain"
]
}
]
}
The entry points to
instructions for searching the catalog
. These instructions describe how to use the WebMCP tool searchDomainCatalog or, when it is unavailable, how to search the site’s JSON index. The address in url therefore leads to a document explaining how to proceed.
According to sections 4.2 and 4.3 :
identifier,displayNameandtypeare required. They define the resource’s identifier, readable name and type.- An entry must contain exactly one of these fields:
url, which points to a document, ordata, which contains the document directly. representativeQueriesshould contain 2–5 example queries. These help index the resource according to user needs. A missing field or a different number of examples triggers a warning from the conformance tool, not a schema validation error.capabilitiesis an optional list of short function names, useful for filtering.
A manifest may also contain additional top-level fields, such as host or specVersion. ARD assigns no meaning to them in its manifest model. This is why "specVersion": "1.0" in our file does not mean that the current ARD specification is version 1.0. The structure is formally defined by the
entry and manifest schema
.
How do you migrate from ai-catalog.json to ard.json?
You can migrate an existing catalog in four steps:
- Check the entries against the current ARD schema, including identifiers, resource addresses and example queries.
- Make the manifest available at
/.well-known/ard.jsonon your own domain. - Add a link to this document in the
<head>section of your pages. - Check that the manifest and the referenced resources can be fetched, and run validation. If you keep the old path for existing clients, keep both versions consistent.
The link can look like this:
<link rel="ard" href="/.well-known/ard.json" type="application/json">
The specification provides a conformance testing tool . It lets you check the manifest and its discovery on the domain.
What does publishing this file achieve?
A manifest makes it easier for software supporting ARD to identify a site’s capabilities. In our example, it describes how to search for domains and articles. For a resource to appear in a particular registry’s results, that registry must discover the source and index it.
Publishing the file alone does not guarantee support by any given assistant or a higher ranking in Google. Test its practical effect in an integration that actually uses ARD: does it fetch the manifest, recognize the entry and know how to use the referenced resource?
See also: What is ARD?
Read also
