repository·main·Indexed 18 days ago
https://github.com/ards-project/ard-specA federated, domain-anchored standard for cataloging, searching, and discovering agentic resources such as MCP servers, A2A agent cards, Skills, and APIs. Built upon the ai-catalog standard, it includes specifications for URN naming patterns, Registry API endpoints (POST /search, GET /agents, and POST /explore), and a Python-based Conformance Testing Tool for verifying implementation compliance.
The ARD API uses a common query object for both POST /search and POST /explore endpoints. The query object consists of two primary members:
text (String): A natural-language description used for semantic relevance. In POST /search, this field is required.filter (Object): Structured constraints using dot-separated field paths (e.g., trustManifest.attestations.type).Filter Semantics:
text relevance AND every constraint in the filter.type, tags, capabilities, or custom metadata.* fields) can be used as a filter key.{
"query": {
"text": "find me a flight booking agent",
"filter": {
"type": ["application/a2a-agent-card+json"],
"tags": ["finance"],
"trustManifest.attestations.type": ["SOC2-Type2"]
}
}
}In the ARD specification (v0.5.0 and later), the federation control parameter is located at the root level of the POST /search request payload. It is a sibling to the query, pageSize, and pageToken parameters.
Do not place the federation parameter inside the query object. The query object (the QueryModel) is shared with the /explore endpoint and must only contain semantic intent and metadata filtering constraints. The federation parameter is a routing instruction that determines how the registry executes and routes the request across the network topology.
{
"federation": "auto",
"query": {
"//": "semantic intent and filters go here"
},
"pageSize": 20,
"pageToken": "abc"
}The ARD discovery specification operates via two distinct layers:
To ensure cross-network uniqueness and decentralized trust, all agent identifiers MUST follow a standardized, domain-anchored URN format: urn:air:<publisher>:<namespace>:<agent-name>.
urn: Mandatory prefix.air: The Namespace Identifier (NID) for the ARD ecosystem.<publisher>: A fully qualified domain name (FQDN) acting as the organizational trust anchor (e.g., acme.com).<namespace>: (Optional) Hierarchical segments for categorization (e.g., finance:trading).<agent-name>: (Mandatory) The specific logical short name (e.g., assistant).urn:air:<publisher>:<namespace>:<agent-name>ARD is built on several key principles to ensure scalability and interoperability:
type field to identify artifacts (e.g., application/mcp-server-card+json), delegating specific metadata definitions to the underlying protocol.url: A remote reference to the artifact document.data: An embedded JSON object containing the full artifact document.In the Agentic Resource Discovery (ARD) specification, a Uniform Resource Name (URN) represents the logical identity (the 'Noun') of an agent or capability, not its physical location.
http://, mTLS, stdio) is defined separately in the catalog entry's url or data properties.The standard URN structure is:
urn:air:<publisher>:<namespace>:<agent-name>
urn:air:<publisher>:<namespace>:<agent-name>The ARD specification supports two tiers of URN publisher configuration depending on your security requirements:
For standard local development, use the RFC 2606 placeholders (*.localhost, example.com). In this mode, there is no active cryptographic identity verification. The placeholders are used strictly to satisfy syntax validation rules and maintain architectural consistency.
If you are testing production zero-trust security meshes (e.g., SPIFFE/SPIRE or mTLS) within a local environment (like a Kubernetes/Istio cluster), use your real production domain (e.g., acme.com) as the URN publisher. This allows your local security mesh to actively validate test certificates against the URN namespace before deployment.
The federation parameter in POST /search allows clients to control how a registry interacts with other registries in the network:
auto: The registry automatically queries upstream registries, merges their results with its own, and returns a single unified response.referrals: The registry returns its own results plus catalog entries for other registries. The client is responsible for deciding which registries to query next.none: The registry searches only its own local index and does not perform any federated lookups.{
"query": {
"text": "find me a flight booking agent"
},
"federation": "referrals"
}ARD uses the type field, formatted as an IANA Media Type, to identify the nature of an artifact. This allows the discovery layer to remain agnostic of the internal schema of specific agent types.
Commonly used (though pending formal registration) media types include:
application/a2a-agent-card+jsonapplication/mcp-server-card+jsonNote for Implementers: While well-known path directories like /.well-known/agent-card.json are officially registered, full type registrations are pending. Intermediaries should avoid strict verification of these types during the transition period.
The ARD specification enforces a strict separation of concerns between semantic search and catalog browsing to ensure performance and relevance integrity:
POST /search (Relevance-Driven): Use this for semantic, natural-language queries. Results are ordered exclusively by match score. To filter results, do not use complex EBNF strings; instead, use the explicit, flat JSON fields provided in the query object (e.g., type, compliance, publisher).
GET /agents (Browse-Driven): Use this for deterministic, SQL-like catalog browsing. This is the only endpoint that supports complex EBNF filter strings and metadata orderBy parameters. There are no relevance scores in this endpoint.
When to use which:
POST /search.GET /agents.