Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [[RFC2119]] [[RFC8174]] when, and only when, they appear in all capitals, as shown here.

The following terms are used throughout this document:

AI Catalog

A JSON document conforming to the application/ai-catalog+json media type that contains an ordered list of catalog entries.

Catalog Entry

A single item in an AI Catalog, identified by a media type and referencing or embedding an AI artifact.

Trust Manifest

A JSON object providing verifiable identity, attestation, and provenance metadata for an AI artifact.

Artifact

Any AI resource described by a catalog entry, such as an MCP server manifest, an A2A agent card, a Claude Code plugin, a dataset descriptor, or a nested AI Catalog.

Media Type

An AI Catalog document is identified by the media type:

application/ai-catalog+json

Top-Level Structure

An AI Catalog document is a JSON object that MUST contain the following members:

specVersion

A string indicating the version of this specification that the catalog conforms to, in "Major.Minor" format (e.g., "1.0"). See Version Handling for compatibility rules.

entries

An array of Catalog Entry objects as defined in Catalog Entry. This array MAY be empty.

For example, a minimal catalog listing three AI artifacts:

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

The following members are OPTIONAL:

host

A Host Info object as defined in Host Info identifying the operator of this catalog.

metadata

An open map of string keys to arbitrary values for custom or non-standard metadata. See Metadata Extensibility for key naming conventions.

Host Info

The Host Info object identifies the operator of the catalog. It MUST contain:

displayName

A string containing the human-readable name of the host (e.g., the organization name).

The following members are OPTIONAL:

identifier

A string containing a verifiable identifier for the host (e.g., a DID or domain name).

documentationUrl

A string containing a URL to the host's documentation.

logoUrl

A string containing a URL to the host's logo.

trustManifest

A Trust Manifest object as defined in Trust Manifest providing verifiable identity and trust metadata for the host itself.

For example:

{
  "displayName": "Acme Enterprise AI",
  "identifier": "did:web:acme-corp.com",
  "documentationUrl": "https://docs.acme-corp.com/ai",
  "logoUrl": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0c..."
}

Catalog Entry

A Catalog Entry object describes a single AI artifact in the catalog. It MUST contain the following members:

identifier

A string identifying this artifact. This SHOULD be a URN [[RFC8141]] or URI [[RFC3986]] (e.g., urn:example:agent:name). See Multi-Version Entries for uniqueness rules when multiple versions are present.

displayName

A string containing a human-readable name for the artifact.

mediaType

A string containing the media type that identifies the type of the referenced artifact. This is the mechanism by which clients determine what kind of AI artifact the entry represents. Well-known values include (but are not limited to):

• application/ai-catalog+json — a nested AI Catalog
• application/a2a-agent-card+json — an A2A Agent Card
• application/mcp-server-card+json — an MCP Server Card
• Any other media type defined by a protocol specification (e.g., application/agentskill+zip for skill definitions)

A Catalog Entry MUST contain exactly one of the following members to provide the artifact content:

url

A string containing a URL where the full artifact document can be retrieved. The document served at this URL SHOULD be served with the media type declared in the mediaType field.

data

A JSON value containing the complete artifact document inline. The structure of this value is determined by the mediaType field and is opaque to this specification.

The following members are OPTIONAL:

description

A string containing a short description of the artifact.

tags

An array of strings serving as keywords for filtering and discovery.

version

A string containing the version of this artifact. Semantic Versioning is RECOMMENDED but not required. See Multi-Version Entries for how versions interact with identifier.

updatedAt

A string containing an ISO 8601 [[RFC3339]] timestamp indicating when this entry was last modified.

metadata

An open map of string keys to arbitrary values for custom data.

publisher

A Publisher object as defined in Publisher Object identifying the entity that publishes this artifact. This is the sole location for publisher information; it is not duplicated in the Trust Manifest.

trustManifest

A Trust Manifest object as defined in Trust Manifest providing verifiable identity and trust metadata for this artifact. See Trust Manifest for details.

Multi-Version Entries

A catalog MAY contain multiple entries with the same identifier and different version values, representing a version history for a single artifact — similar to a package registry.

When version is present, the combination of identifier and version MUST be unique within the catalog. When version is absent, identifier alone MUST be unique. The identifier SHOULD be stable across versions and catalog locations so that the same logical artifact can be recognized wherever it appears.

Clients that need only the latest version SHOULD sort entries sharing the same identifier by version (when parseable as a semantic version) or by updatedAt, and select the most recent. Clients that need a specific version SHOULD match on both identifier and version.

For example, a catalog listing two versions of the same agent:

{
  "specVersion": "1.0",
  "entries": [
    {
      "identifier": "urn:acme:agent:finance",
      "displayName": "Acme Finance Agent",
      "version": "2.1.0",
      "mediaType": "application/a2a-agent-card+json",
      "url": "https://api.acme-corp.com/agents/finance/v2.1.json",
      "updatedAt": "2026-03-15T10:00:00Z"
    },
    {
      "identifier": "urn:acme:agent:finance",
      "displayName": "Acme Finance Agent",
      "version": "2.0.0",
      "mediaType": "application/a2a-agent-card+json",
      "url": "https://api.acme-corp.com/agents/finance/v2.0.json",
      "updatedAt": "2026-01-20T08:00:00Z"
    }
  ]
}

Both entries share the same identifier but have distinct version values, so the combination is unique.

Publisher Object

The Publisher object identifies the entity responsible for an artifact. It appears on the Catalog Entry and is the canonical location for publisher information. It MUST contain:

identifier

A string containing a verifiable identifier for the publisher organization.

displayName

A string containing the human-readable name of the publisher.

The following members are OPTIONAL:

identityType

A string providing a type hint for the publisher identifier (e.g., "did", "dns").

Identity

A Trust Manifest MUST contain:

identity

A string containing a globally unique URI [[RFC3986]] that serves as the primary subject identifier for this artifact. This SHOULD be a DID, SPIFFE ID, or URL.

When a Trust Manifest appears within a Catalog Entry, the identity field MUST match the entry's identifier field. This binding ensures trust claims are unambiguously associated with the catalog artifact. Consumers MUST reject a Trust Manifest whose identity does not match the containing entry's identifier.

When a Trust Manifest appears on a Host Info object, identity SHOULD match the host's identifier field when present.

When multiple entries share the same identifier (with different version values), each entry MAY carry its own Trust Manifest. There is no requirement that all versions carry identical trust metadata — trust properties may evolve across versions.

Optional Members

The following members are OPTIONAL:

identityType

A string providing a type hint for the identity URI (e.g., "did", "spiffe", "dns"). This field is OPTIONAL when the type is evident from the URI scheme.

trustSchema

A Trust Schema object as defined in Trust Schema.

attestations

An array of Attestation objects as defined in Attestation. This is the mechanism for verifiable claims including publisher identity verification (using attestation type "publisher-identity"), compliance certifications, and other proofs.

provenance

An array of Provenance Link objects as defined in Provenance Link.

privacyPolicyUrl

A string containing a URL to the privacy policy governing this artifact.

termsOfServiceUrl

A string containing a URL to the terms of service.

signature

A string containing a detached JWS [[RFC7515]] signature computed over the Trust Manifest content. This enables integrity verification of the trust metadata independent of the artifact.

metadata

An open map of string keys to arbitrary values for extending trust metadata.

For example, a Trust Manifest with identity, attestations, and provenance:

{
  "identity": "urn:acme:agent:finance",
  "identityType": "did",
  "trustSchema": {
    "identifier": "urn:trust:acme-enterprise-v1",
    "version": "1.0",
    "governanceUri": "https://acme-corp.com/trust/governance.pdf",
    "verificationMethods": ["did", "x509"]
  },
  "attestations": [
    {
      "type": "publisher-identity",
      "uri": "https://trust.acme-corp.com/certs/publisher.jwt",
      "mediaType": "application/jwt",
      "description": "Verifies did:web:acme-corp.com as publisher"
    },
    {
      "type": "SOC2-Type2",
      "uri": "https://trust.acme-corp.com/reports/soc2.pdf",
      "mediaType": "application/pdf",
      "digest": "sha256:a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890"
    }
  ],
  "provenance": [
    {
      "relation": "publishedFrom",
      "sourceId": "https://github.com/acme-corp/finance-agent",
      "sourceDigest": "sha256:fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321"
    }
  ],
  "privacyPolicyUrl": "https://acme-corp.com/legal/privacy",
  "termsOfServiceUrl": "https://acme-corp.com/legal/terms",
  "signature": "eyJhbGciOiJFUzI1NiJ9..detached-jws-signature"
}

Trust Schema Object

A Trust Schema object describes the trust framework applied to the artifact. It MUST contain:

identifier

A string identifying the trust schema.

version

A string indicating the schema version.

The following members are OPTIONAL:

governanceUri

A string containing a URI to the governance policy document.

verificationMethods

An array of strings identifying the verification methods supported (e.g., "did", "x509", "dns-01").

For example:

{
  "identifier": "urn:trust:acme-enterprise-v1",
  "version": "1.0",
  "governanceUri": "https://acme-corp.com/trust/governance.pdf",
  "verificationMethods": ["did", "x509"]
}

Attestation Object

An Attestation object provides verifiable proof of a claim. It MUST contain:

type

A string identifying the attestation type (e.g., "SOC2-Type2", "HIPAA-Audit", "ISO27001").

uri

A string containing the location of the attestation document. This may be an HTTPS URL or an inline Data URI [[RFC2397]].

mediaType

A string indicating the format (e.g., "application/pdf", "application/jwt").

The following members are OPTIONAL:

digest

A string containing a cryptographic hash for integrity verification (e.g., "sha256:abcd1234...").

size

An unsigned integer indicating the size of the attestation in bytes.

description

A string containing a human-readable label.

For example, a compliance attestation with integrity verification:

{
  "type": "SOC2-Type2",
  "uri": "https://trust.acme-corp.com/reports/soc2-2026.pdf",
  "mediaType": "application/pdf",
  "digest": "sha256:a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890",
  "size": 245760,
  "description": "SOC2 Type 2 audit report for Acme Finance Agent (2026)"
}

Provenance Link Object

A Provenance Link records lineage information. It MUST contain:

relation

A string describing the relationship (e.g., "materializedFrom", "derivedFrom", "publishedFrom").

sourceId

A string identifying the source artifact or data.

The following members are OPTIONAL:

sourceDigest

A string containing the digest of the source.

registryUri

A string containing the URI of the registry holding the source.

statementUri

A string containing the URI of a provenance statement document.

signatureRef

A string referencing the key used to sign the provenance statement.

For example, a provenance link recording that an artifact was built from a specific source commit and published through an OCI registry:

{
  "relation": "publishedFrom",
  "sourceId": "https://github.com/acme-corp/finance-agent",
  "sourceDigest": "sha256:fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321",
  "registryUri": "oci://registry.acme-corp.com/agents/finance",
  "statementUri": "https://trust.acme-corp.com/provenance/finance-agent-v2.1.json",
  "signatureRef": "did:web:acme-corp.com#key-1"
}

Verification Procedures

This section describes how consumers verify the trust metadata carried by a Trust Manifest. Verification is OPTIONAL — consumers that do not need trust assurance can skip this entirely.

sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

Nested Catalog Entries

A catalog entry whose mediaType is application/ai-catalog+json references (via url) or embeds (via data) another AI Catalog document. This mechanism supports two complementary use cases:

Organizational hierarchy. An enterprise with thousands of artifacts can partition its catalog into sub-catalogs by department, product line, or region. Each sub-catalog is an independent AI Catalog document with its own host and entries:

{
  "specVersion": "1.0",
  "host": {
    "displayName": "Acme Enterprise AI",
    "identifier": "did:web:acme-corp.com"
  },
  "entries": [
    {
      "identifier": "urn:acme:catalog:finance",
      "displayName": "Finance Services",
      "mediaType": "application/ai-catalog+json",
      "url": "https://acme.com/catalogs/finance.json"
    },
    {
      "identifier": "urn:acme:catalog:ml",
      "displayName": "ML Models",
      "mediaType": "application/ai-catalog+json",
      "url": "https://acme.com/catalogs/ml.json"
    },
    {
      "identifier": "urn:acme:catalog:devops",
      "displayName": "DevOps Tools",
      "mediaType": "application/ai-catalog+json",
      "url": "https://acme.com/catalogs/devops.json"
    }
  ]
}

Multi-artifact packaging. An entry with a publisher that contains a nested catalog may be interpreted as a set of items that could be acquired as a unit. For example, a finance plugin that ships an A2A agent, an MCP server, and a dataset together:

{
  "identifier": "urn:acme:plugin:finance-suite",
  "displayName": "Finance Plugin",
  "mediaType": "application/ai-catalog+json",
  "url": "https://acme.com/plugins/finance-suite.json",
  "publisher": {
    "identifier": "did:web:acme-corp.com",
    "displayName": "Acme Financial Corp"
  }
}

The document at that URL would itself be an AI Catalog containing the A2A agent, MCP server, and dataset entries.

A nested catalog entry is a regular catalog entry — it has an identifier, may carry a trustManifest, and may include a publisher. An entry inside a nested catalog MAY reuse the same identifier as an entry elsewhere; this indicates the same logical artifact.

Clients processing nested catalogs SHOULD impose a maximum nesting depth to prevent circular references. A depth limit of 4 is RECOMMENDED. Implementations MAY support deeper nesting but SHOULD document their limit.

Key Naming

Metadata keys MUST be non-empty strings. To avoid collisions between independent publishers, the following conventions are RECOMMENDED:

• Reverse-DNS prefix for vendor-specific keys: com.example.confidenceScore, io.acme.deploymentRegion.
• Short, unqualified names for keys the publisher considers broadly useful and unlikely to conflict: repository, homepage, license.
• Avoid keys that duplicate defined catalog fields (displayName, description, tags, version). Consumers MAY ignore metadata entries that shadow standard fields.

Reserved Keys

No metadata keys are reserved by this specification. Future specification versions MAY promote commonly used metadata keys into standard fields. When this occurs, the metadata key SHOULD be retained for backward compatibility and the standard field takes precedence.

Value Types

Metadata values MAY be any valid JSON type (string, number, boolean, array, object, null). Consumers that do not recognize a metadata key SHOULD ignore it.

Version Format

The specVersion value is a "Major.Minor" string (e.g., "1.0", "1.1", "2.0"). Major and minor components are non-negative integers.

Compatibility Rules

Minor version increments (e.g., 1.0 → 1.1)

The specification adds new OPTIONAL fields or features. Documents conforming to a higher minor version are backward-compatible with consumers that understand the same major version. Consumers MUST ignore unrecognized fields.

Major version increments (e.g., 1.x → 2.0)

The specification introduces breaking changes (removed fields, changed semantics, new required fields). Consumers that do not support the major version SHOULD reject the document with an informative error rather than silently misinterpreting it.

Consumer Behavior

Consumers SHOULD:

• Parse the specVersion field before processing the document.
• Accept documents whose major version matches their supported major version, regardless of minor version differences.
• Ignore unrecognized fields (forward compatibility within a major version).
• Reject documents whose major version is higher than the highest major version they support, with an informative error message.

Producer Behavior

Producers MUST set specVersion to the version of this specification they implement. Producers SHOULD NOT set specVersion to a version higher than they actually conform to.

Location Independence

An AI Catalog document MAY be served from any URL. It is identified by its media type (application/ai-catalog+json) and its specVersion field, not by its URL path. Catalogs are equally valid when hosted at an arbitrary path, embedded in a registry response, packaged in an archive, or distributed as a local file.

When served over HTTP, the document SHOULD be served with the media type application/ai-catalog+json.

Well-Known URI

To support automated discovery, hosts MAY serve an AI Catalog at the following well-known URI [[RFC8615]]:

/.well-known/ai-catalog.json

Clients performing domain-level discovery SHOULD attempt to retrieve this well-known URL. If a valid AI Catalog document is returned, the client SHOULD use the url entries to retrieve individual artifacts and their associated Trust Manifests.

Use of the well-known URI is OPTIONAL. Hosts that publish catalogs at other locations (e.g., as part of an API response or a package registry) are fully conformant.

Dynamic Discovery

Implementing protocols MAY support dynamic catalog generation through their own mechanisms, such as providing different catalog content based on a caller's identity or query parameters. Defining dynamic discovery behavior is out of scope for this specification.

Link Relation Discovery

Websites MAY advertise their AI Catalog by including an ai-catalog link relation in HTTP responses or HTML documents. This enables AI agents, crawlers, and other automated clients to discover the catalog associated with any website without prior knowledge of its location.

HTTP Link header. A server MAY include a Link header [[RFC8288]] in HTTP responses:

Link: <https://example.com/catalog/ai.json>; rel="ai-catalog"

HTML <link> element. An HTML page MAY include a link element in the document head:

<link rel="ai-catalog" href="/catalog/ai.json"
      type="application/ai-catalog+json">

Agent-driven discovery. AI agents that interact with websites (for example, agents following user instructions to "find tools on this site" or browsing on behalf of a user) SHOULD check for the ai-catalog link relation on the target website. The discovery procedure is:

1. Fetch the target URL and inspect the HTTP response headers for a Link header with rel="ai-catalog".
2. If no Link header is present and the response is an HTML document, parse the document for a <link> element with rel="ai-catalog".
3. If neither is found, optionally fall back to the well-known URI /.well-known/ai-catalog.json as described in Well-Known URI.
4. Retrieve the discovered URL. If the response has a media type of application/ai-catalog+json and contains a valid specVersion field, treat it as the site's AI Catalog.

This mechanism allows any website to surface its AI tools, agents, and services to visiting agents through a standard, machine-readable pointer — without requiring changes to the site's visible content.

Level 1: Minimal Catalog

A conformant Minimal Catalog is a JSON document with media type application/ai-catalog+json that contains:

• specVersion — the specification version string
• entries — an array of Catalog Entry objects, each containing at minimum identifier, displayName, mediaType, and exactly one of url or data

All other fields (host, publisher, trustManifest, metadata) are OPTIONAL. This level is sufficient for use cases that only need a simple list of AI artifacts — for example, a catalog of MCP servers or A2A agents.

Level 2: Discoverable Catalog

In addition to Level 1 requirements, a Discoverable Catalog:

• Includes a host object identifying the catalog operator
• MAY be served at the well-known URI /.well-known/ai-catalog.json to enable automated domain-level discovery

Level 3: Trusted Catalog

In addition to Level 2 requirements, a Trusted Catalog:

• Includes trustManifest objects on entries and/or the host, as defined in Trust Manifest
• MAY include publisher objects on entries with verifiable identifiers
• Enables verifiable identity, compliance attestations, and provenance tracking

Implementations at any level are fully conformant with this specification. Consumers MAY ignore fields defined at higher conformance levels and SHOULD gracefully handle their absence.

Trust Layers

This specification supports a progressive trust model. Each layer builds on the previous one, adding confidence without requiring all consumers to implement every layer. Consumers choose the level appropriate to their threat model.

Layer 0 — Transport Security

The catalog and artifacts are served over HTTPS (TLS 1.2 or later). The consumer trusts the TLS certificate chain and DNS resolution. This prevents passive eavesdropping and casual tampering but does not protect against compromised hosting or DNS hijack.

Layer 1 — Trust Manifest with Provenance

The catalog entry includes a Trust Manifest containing provenance links with sourceDigest values. After fetching an artifact, the consumer can hash the content and compare it to the digest recorded in the provenance link. This detects artifact tampering in transit. However, because the Trust Manifest is a peer element in the catalog (not embedded in the artifact), an attacker who controls the catalog document can substitute both the artifact URL and the Trust Manifest with matching values. Digest verification without signature verification guards against transport-level tampering but not catalog-level substitution.

Layer 2 — Signed Trust Manifest

The Trust Manifest includes a signature field (detached JWS). The consumer verifies the signature against the publisher's public key before trusting any claims in the Trust Manifest — including provenance digests, attestations, and identity bindings. This closes the substitution gap from Layer 1: an attacker cannot forge a signed Trust Manifest without the publisher's private key. Consumers SHOULD verify signatures when present and SHOULD reject Trust Manifests whose signature does not validate.

Layer 3 — Content-Addressed Distribution (OCI)

The catalog is distributed through an OCI registry where all content — entries, artifacts, and Trust Manifests — is addressed by cryptographic digest. The registry enforces integrity: substitution is impossible because any change produces a different digest. Cosign or Notation signatures on OCI manifests provide an additional layer of publisher authentication.

Consumers that rely on trust metadata for security decisions SHOULD implement at least Layer 2 (signature verification). Consumers that only implement Layer 0 or Layer 1 SHOULD treat Trust Manifest content as advisory, not authoritative.

Nested Catalog Depth and Circular References

Clients processing nested catalogs MUST enforce a maximum recursion depth to prevent denial-of-service attacks via deeply nested or circular catalog references. A maximum depth of 4 is RECOMMENDED.

Depth limits alone do not prevent circular references at shallow depths (e.g., Catalog A → Catalog B → Catalog A). Clients SHOULD track the set of catalog URLs visited during recursive resolution and reject any catalog URL that has already been fetched in the current traversal path.

Catalog Poisoning

An attacker who can modify a catalog document (e.g., through a compromised hosting account or DNS hijack) can redirect consumers to malicious artifacts by changing url values or injecting new entries.

The trust layers described above provide progressive defense against this threat:

• Layer 0 relies on HTTPS certificate management to prevent unauthorized modification.
• Layer 1 enables post-fetch integrity checks but does not prevent whole-entry substitution.
• Layer 2 prevents Trust Manifest forgery, ensuring provenance digests and attestations are authentic.
• Layer 3 makes modification structurally impossible through content-addressing.

Identifier Typosquatting

Catalog entries are identified by URIs/URNs. An attacker can register identifiers similar to legitimate ones (e.g., urn:acme:agent:financ vs. urn:acme:agent:finance) to trick consumers into using a malicious artifact.

Registries and consumers SHOULD implement similarity checks on identifiers. Publishers SHOULD use identifiers anchored to domains they control (e.g., DIDs or domain-scoped URNs).

Stale Attestations

Attestation documents referenced in Trust Manifests have no built-in expiry mechanism in this specification. A SOC2 report from a previous year may no longer reflect current practices.

Consumers SHOULD:

• Check the updatedAt field on catalog entries to assess freshness.
• Independently verify attestation documents are current when making trust decisions.
• Treat attestations as evidence, not guarantees — the attestation indicates a claim was made, not that it remains valid indefinitely.

Future versions of this specification MAY add validFrom and expiresAt fields to the Attestation object.

Embedded Content Safety

When the data field contains embedded artifact content, consumers MUST treat it as untrusted input. In particular:

• Content with HTML or script-capable media types MUST be sandboxed and MUST NOT be executed in the consumer's security context.
• Consumers SHOULD validate that the data content is well-formed JSON (or the expected format for the declared mediaType) before processing.

Privacy Considerations

Logo URLs SHOULD use Data URIs [[RFC2397]] to avoid leaking client information through image fetch requests. Publishers SHOULD carefully consider what information is included in metadata extension fields.