Wat is ai-catalog.json en hoe werkt het?
Auteur: Redactie Domeny.ForSale Gepubliceerd Bijgewerkt
In het kort: /.well-known/ai-catalog.json is het eerdere pad voor het publiceren van een resourcemanifest voor AI-agenten. De specificatie van Agentic Resource Discovery (ARD) beschrijft dit als de voorganger van /.well-known/ard.json. Zo’n manifest beschrijft beschikbare tools, agenten of gebruiksinstructies in een gestructureerd JSON-formaat. Gebruik bij een nieuwe implementatie het pad ard.json en een HTML-link met rel="ard".
Dit artikel is gebaseerd op de ARD-specificatie v0.91 van 26 augustus 2026, aangeduid als Proposal, oftewel een voorstel. De stand van de documentatie is gecontroleerd op 3 oktober 2026.
Waarvoor dient een resourcecatalogus voor agenten?
Een assistent die een externe tool nodig heeft, moet eerst vaststellen wat die tool doet en waar de beschrijving te vinden is. Met een manifest kan de uitgever deze informatie in een gemeenschappelijke structuur aanbieden. De afzonderlijke vermeldingen kunnen bijvoorbeeld verwijzen naar een beschrijving van een MCP-server, een A2A-agentkaart of een bestand met instructies om een taak uit te voeren, een zogenoemde skill.
Binnen ARD vormt het publiceren van het manifest het statische deel van het ontdekken van resources. Een register heeft een andere rol: het haalt vermeldingen op, indexeert ze en maakt ze doorzoekbaar. Zo kan een client zoeken op een concrete behoefte en passende resources ontvangen. Het JSON-bestand zelf voert geen tools uit; het betreffende protocol of de bijbehorende instructie bepaalt hoe ze worden gestart. Deze lagen worden beschreven in hoofdstukken 3 en 5 van de specificatie .
Waarom wordt nu ard.json gebruikt?
In hoofdstuk 5.1 geeft de specificatie eenduidige regels voor het vinden van manifesten:
| Mechanisme | Huidige naam | Eerdere naam |
|---|---|---|
| Bestand op het domein | /.well-known/ard.json | /.well-known/ai-catalog.json |
| Link in HTML | rel="ard" | rel="ai-catalog" |
| Ondersteuning door een ARD-client | Verplicht bij het ontdekken van vermeldingen van het domein | Optionele achterwaartse compatibiliteit |
Een client die aan de specificatie voldoet en resources van een domein ontdekt, moet /.well-known/ard.json ophalen en de link met rel="ard" volgen. De client mag daarnaast het eerdere pad en de linkrelatie ai-catalog controleren. Als hij dat doet, behandelt hij deze als gelijkwaardige bronnen van vermeldingen.
Dat betekent dat een website die alleen ai-catalog.json aanbiedt, door een correct werkende ARD-client kan worden overgeslagen. De specificatie beveelt de overstap naar ard.json aan. Het oude adres naast het nieuwe behouden is een optie voor oudere integraties, geen vereiste voor een nieuwe implementatie.
Hoe ziet een geldig manifest eruit?
Het document bevat een array entries met beschrijvingen van de afzonderlijke resources. Het volgende voorbeeld is een verkorte versie van
het manifest van Domeny.ForSale
:
{
"entries": [
{
"identifier": "urn:air:domeny.forsale:skill:domain-catalog-search",
"displayName": "Zoekfunctie voor de catalogus van Domeny.ForSale",
"type": "text/markdown; profile=\"urn:air:agent-skills\"",
"url": "https://domeny.forsale/.well-known/agent-skills/domain-catalog-search/SKILL.md",
"capabilities": ["searchDomainCatalog"],
"representativeQueries": [
"vind een domeinnaam te koop voor een webwinkel",
"toon artikelen over het kiezen en kopen van een domeinnaam"
]
}
]
}
De vermelding verwijst naar
de instructie voor het doorzoeken van de catalogus
. Die beschrijft het gebruik van de WebMCP-tool searchDomainCatalog en, als die niet beschikbaar is, het doorzoeken van de JSON-index van de website. Het adres in url leidt dus naar een document dat de werkwijze beschrijft.
Volgens hoofdstukken 4.2 en 4.3 :
identifier,displayNameentypezijn verplicht. Ze geven de identificatie, de leesbare naam en het type van de resource aan.- Een vermelding moet precies één van deze velden bevatten:
url, dat naar het document verwijst, ofdata, dat het document rechtstreeks bevat. representativeQuerieshoort 2–5 voorbeeldzoekvragen te bevatten. Deze helpen bij het indexeren van de resource op basis van gebruikersbehoeften. Als het veld ontbreekt of een ander aantal voorbeelden bevat, geeft de conformiteitstest een waarschuwing, geen fout bij de schemavalidatie.capabilitiesis een optionele lijst met korte functienamen, handig voor het filteren.
Het manifest mag ook extra velden op het hoogste niveau bevatten, zoals host of specVersion. ARD kent hieraan geen betekenis toe binnen zijn manifestmodel. Daarom betekent "specVersion": "1.0" in ons bestand niet dat de huidige ARD-specificatie versie 1.0 heeft. De structuur is formeel vastgelegd in
het schema voor vermeldingen en manifesten
.
Hoe stap je over van ai-catalog.json naar ard.json?
Je kunt een bestaande catalogus in vier stappen migreren:
- Controleer de vermeldingen aan de hand van het huidige ARD-schema, inclusief identificaties, resourceadressen en voorbeeldzoekvragen.
- Publiceer het manifest op
/.well-known/ard.jsonop je eigen domein. - Voeg in de
<head>-sectie van de pagina’s een link naar dit document toe. - Controleer of het manifest en de genoemde resources kunnen worden opgehaald en voer een validatie uit. Als je het oude pad voor bestaande clients behoudt, houd beide versies dan consistent.
De link kan er zo uitzien:
<link rel="ard" href="/.well-known/ard.json" type="application/json">
De specificatie biedt een tool voor conformiteitstests . Daarmee kun je het manifest controleren en testen of het op het domein kan worden gevonden.
Wat levert het publiceren van zo’n bestand op?
Een manifest maakt het voor software die ARD ondersteunt eenvoudiger om te herkennen wat de website kan bieden. In ons voorbeeld beschrijft het hoe domeinnamen en artikelen kunnen worden doorzocht. Om een resource in de zoekresultaten van een bepaald register te laten verschijnen, moet dat register de bron vinden en indexeren.
Alleen het publiceren van het bestand garandeert niet dat elke assistent het ondersteunt of dat de website hoger in Google verschijnt. Controleer het praktische effect in een integratie die daadwerkelijk ARD gebruikt: haalt die het manifest op, herkent die de vermelding en kan die de aangewezen resource gebruiken?
Zie ook: Wat is ARD?
Lees ook
