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: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"
    }
  ]
}

The following members are OPTIONAL:

host

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

extensions

A JSON object (map) containing custom, vendor-specific, or non-standard fields. See Extensions for definitions and official extension types.

signature

A string containing a detached JWS [[RFC7515]] signature computed over the JCS-canonicalized [[RFC8785]] catalog document (excluding the signature member itself), providing catalog-level integrity over the entries array and host. It is verified exactly as a Trust Manifest signature (see Trust Manifest Signatures). See Trust Manifest Substitution.

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 uniquely identifying this artifact. This field is an open text format (e.g., any valid URI or URN is accepted). However, to ensure interoperability, identity uniqueness, and discoverability, the standard urn:air naming structure is HIGHLY RECOMMENDED and MUST be used for open or federated systems.

Standard Naming Format: urn:air:{publisher}:{namespace}:{name}

• {publisher}: The domain name of the organization publishing the artifact (e.g., example.com).
• {namespace}: The logical namespace, which can contain one or more colon-separated categories (e.g., mcp, skill, agent, finance:agent).
• {name}: The stable, unique name of the artifact within the publisher's namespace.

Examples:

• urn:air:example.com:skill:code-review
• urn:air:example.com:mcp:weather

For closed or local systems where a different identifier format is used, client implementations are responsible for parsing and processing the custom format as appropriate.

See Multi-Version Entries for uniqueness rules when multiple versions are present.

type

A string containing the identifier that specifies the type of the referenced artifact. This field is an open text format, so any string value is accepted. However, to ensure interoperability, it is RECOMMENDED to use one of the following recognized "known types" in the ecosystem when applicable, partitioned by their respective governance boundaries:

Core Protocol Types (Governed by the AI Catalog WG):

• application/ai-catalog+json — a nested AI Catalog
• application/agent-card+json — reserved for a generic Agent Card format

Integrated Ecosystem & Third-Party Types (Governed externally):

• application/a2a-agent-card+json — an A2A Agent Card
• application/mcp-server-card+json — an MCP Server Card
• application/agent-skills+json — Agent Skill Metadata json file
• application/agent-skills+md — an Agent Skill defined in a standard Markdown file (the suffix +md is to be registered)
• application/agent-skills+zip — an Agent Skill bundle (ZIP archive)
• application/agent-skills+gzip — an Agent Skill bundle (gzipped tarball)

These values are designed to align with official IANA media type registration standards. Standard ecosystem types use registered structured syntax suffixes (+json, +zip, +gzip). For any new or custom types not listed here, it is up to the specific client implementation to handle them correctly.

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 type field.

data

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

The following members are OPTIONAL:

displayName

A string containing a human-readable name for the artifact. This field SHOULD be set only when the referenced artifact does not already carry its own canonical human-readable name — for example a raw dataset (application/parquet), a model blob, or a skill bundle (application/agent-skills+zip), none of which embed a self-describing name. When the referenced artifact does carry such a name — for example the name field of an A2A Agent Card or the title field of an MCP Server Card — that artifact is the authoritative source and displayName SHOULD be omitted to avoid duplicating a value that can drift out of sync. When displayName is present, however, it takes precedence: it is the authoritative value for display, and a consumer SHOULD render it as given even when it differs from a name carried by the referenced artifact. Setting displayName is how a publisher deliberately overrides the artifact's own name. See Resolving an Artifact's Display Name for the full consumer resolution order.

description

A string containing a short description of the artifact. Like displayName, description is OPTIONAL and follows the same authoritative-source rule: when the referenced artifact carries its own canonical description — for example the description field of an A2A Agent Card or an MCP Server Card — that artifact is the authoritative source and entry description SHOULD be omitted to avoid duplicating a value that can drift out of sync. When entry description is present, however, it takes precedence: a consumer SHOULD render it as given even when it differs from a description carried by the referenced artifact, which is how a publisher provides a listing-specific blurb. See Resolving an Artifact's Description for the full consumer resolution order.

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.

Like displayName and description, version can restate a value the referenced artifact already carries (an A2A Agent Card version, an MCP Server Card version), and when a single entry references such an artifact the entry version SHOULD be omitted to avoid drift — the consumer can read it from the artifact. Unlike displayName and description, however, version is not merely cosmetic: it is part of the entry's uniqueness key, so it is REQUIRED when a catalog lists multiple versions of the same identifier (see Multi-Version Entries). A present version is used for catalog-level sorting and selection rather than as a free-form display override, so it SHOULD equal the version the referenced artifact reports; an entry version that contradicts the artifact's own version is a publishing error, not a deliberate override. See Resolving an Artifact's Version for the full consumer resolution order.

updatedAt

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

extensions

A JSON object (map) containing 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:air:acme.com:agent:finance",
      "version": "2.1.0",
      "type": "application/a2a-agent-card+json",
      "url": "https://api.acme-corp.com/agents/finance/v2.1.json",
      "updatedAt": "2026-03-15T10:00:00Z"
    },
    {
      "identifier": "urn:air:acme.com:agent:finance",
      "version": "2.0.0",
      "type": "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; these are illustrative and the set of identity schemes is open.

When a Trust Manifest appears within a Catalog Entry, the identity field's trust domain MUST align with the publisher domain in the containing entry's identifier field. This binding ensures trust claims are associated with the authorized publisher namespace even when identity and identifier use different URI schemes. Consumers MUST reject a Trust Manifest whose identity domain does not align with the publisher domain in the containing entry's identifier. The identity is carried here so domain binding is part of the signed payload, rather than inferred only from unsigned entry context.

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.

Manifest Validity

A Trust Manifest exists to carry verifiable trust evidence; an empty one adds nothing and misleads consumers into believing trust metadata is present. Beyond the required identity, a Trust Manifest MUST therefore contain at least one substantive trust member:

• a signature (with its required subject and issuedAt),
• a non-empty attestations array,
• a non-empty provenance array, or
• a trustSchema.

The members identity and identityType (which identify the workload principal) and the informational members privacyPolicyUrl, termsOfServiceUrl, and extensions do NOT satisfy this requirement. subject, issuedAt, and expiresAt are not substantive on their own: an unsigned subject digest is attacker-settable and unverifiable, so they count only as part of a signature.

A Trust Manifest that would carry only non-substantive members MUST be omitted entirely rather than included empty — the trustManifest member is itself OPTIONAL, so no information is lost. Consumers SHOULD treat a Trust Manifest that violates this rule as if no Trust Manifest were present.

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.

subject

A Subject object as defined in Subject Binding that cryptographically binds this Trust Manifest to the specific artifact it describes. A Trust Manifest that carries a signature MUST include a subject.

issuedAt

A string containing an ISO 8601 [[RFC3339]] timestamp indicating when the Trust Manifest was created and signed. A Trust Manifest that carries a signature MUST include issuedAt.

expiresAt

A string containing an ISO 8601 [[RFC3339]] timestamp after which the Trust Manifest MUST be considered stale. Consumers SHOULD reject a Trust Manifest whose expiresAt is in the past.

signature

A string containing a detached JWS [[RFC7515]] signature computed over the canonicalized Trust Manifest content, including the subject and issuedAt members. Because the signed payload commits to the artifact digest carried in subject, neither the trust claims nor the artifact reference can be substituted without detection. See Trust Manifest Signatures.

extensions

A JSON object (map) for extending trust metadata. When the Trust Manifest carries a signature, this object is part of the signed payload; use it for extensions that must be cryptographically bound to the manifest.

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

{
  "identity": "did:web:acme.com: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",
      "description": "Verifies did:web:acme-corp.com as publisher"
    },
    {
      "type": "SOC2-Type2",
      "uri": "https://trust.acme-corp.com/reports/soc2.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",
  "subject": {
    "url": "https://api.acme-corp.com/agents/finance/v2.1.json",
    "type": "application/a2a-agent-card+json",
    "digest": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
  },
  "issuedAt": "2026-03-15T10:00:00Z",
  "signature": "eyJhbGciOiJFUzI1NiJ9..detached-jws-signature"
}

Subject Binding

The Subject object binds a Trust Manifest to the specific artifact it describes, closing the substitution gap in which an attacker who controls the catalog document leaves a validly-signed Trust Manifest in place but repoints the entry to a different artifact. Because the Subject is part of the signed payload, the artifact reference and its content digest cannot be changed without invalidating the signature.

A Subject object MUST contain:

type

A string containing the media type of the bound artifact. This MUST equal the containing Catalog Entry's type.

digest

A string containing the cryptographic digest of the artifact content, in the format defined in Digest Format. For an artifact referenced by url, the digest is computed over the exact bytes served. For an artifact embedded in data, the digest is computed over the JCS-canonicalized [[RFC8785]] JSON value.

The following member is OPTIONAL:

url

A string containing the URL of the bound artifact. When present, it MUST equal the containing Catalog Entry's url. Consumers MUST reject a Trust Manifest whose subject.url does not match the entry's url.

A Trust Manifest that carries a signature MUST include a subject. When verifying such a manifest, consumers MUST confirm that the fetched artifact's media type and digest match the subject before relying on any claim in the Trust Manifest. See Verifying Artifact Integrity.

The subject.type and subject.url intentionally restate the entry's type and url so that those values fall within the signed payload. This is a deliberate duplication, not redundant metadata: without it, an attacker who controls the catalog document could change the entry's media type or location without invalidating the 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]].

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",
  "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 type 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:air:acme.com:catalog:finance",
      "displayName": "Finance Services",
      "type": "application/ai-catalog+json",
      "url": "https://acme.com/catalogs/finance.json"
    },
    {
      "identifier": "urn:air:acme.com:catalog:ml",
      "displayName": "ML Models",
      "type": "application/ai-catalog+json",
      "url": "https://acme.com/catalogs/ml.json"
    },
    {
      "identifier": "urn:air:acme.com:catalog:devops",
      "displayName": "DevOps Tools",
      "type": "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:air:acme.com:plugin:finance-suite",
  "displayName": "Finance Plugin",
  "type": "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.

Format and Key Naming

The extensions field is a JSON object (map). Each key in the object MUST represent the extension type (namespace), and the corresponding value contains the extension data.

To avoid collisions between independent publishers, the keys MUST be a valid URL or a reverse-DNS string:

• Reverse-DNS prefix for vendor-specific extensions: com.example.confidenceScore, io.acme.deploymentRegion.
• URL prefix for publicly accessible extension schemas: https://cisco.com/extensions/security-scan.

Consumers that do not recognize an extension key MUST ignore it without throwing an error.

For example, a catalog entry with extensions representing metadata and a custom schema:

{
  "specVersion": "1.0",
  "entries": [
    {
      "identifier": "urn:air:treasury.gov:okf:fiscaldata",
      "type": "text/vnd.okf+markdown",
      "tags": ["finance", "treasury"],
      "extensions": {
        "https://ai-catalog.org/extensions/metadata": {
          "location": "US-West",
          "environment": "staging",
          "version-compatible": [">=1.0.0"]
        },
        "https://openknowledgeformat.org/ns#": {
          "@context": {
            "us-gaap": "https://xbrl.fasb.org/us-gaap/",
            "ifrs": "https://xbrl.ifrs.org/taxonomy/"
          },
          "type": "Financial Dataset",
          "taxonomy": "us-gaap",
          "conformsTo": ["us-gaap:Revenue", "ifrs:Revenue"]
        }
      }
    }
  ]
}

Official Extensions

While publishers are free to create custom extensions, this specification defines a set of "Official" known types for commonly requested schemas:

1. Metadata (https://ai-catalog.org/extensions/metadata) - Used to store generic, schemaless key-value pairs.

As custom extensions become highly popular, the AI-Catalog TSC may promote them to Official Known Types or core standard fields in future specification versions.

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 entries' url values to retrieve individual artifacts. Trust metadata, when present, is carried inline on the entries as 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, type, and exactly one of url or data

All other fields (host, publisher, trustManifest, extensions) 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. A trustManifest, when present at any level, MUST be substantive (see Manifest Validity).

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 a trustManifest object on every entry whose trust is to be relied upon, and MAY include one on the host, as defined in Trust Manifest
• Each such trustManifest MUST carry a signature, a subject binding it to the artifact (Subject Binding), and an issuedAt timestamp
• Consumers MUST verify the signature, anchor the identity (Trust Anchoring), and confirm the subject digest before relying on any claim
• SHOULD provide catalog-level integrity, either by serving the catalog through a content-addressed channel (see Security Considerations) or by including a top-level catalog signature
• 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) and a subject that binds the signature to the artifact's content digest (see Subject Binding). The consumer verifies the signature, anchors the signer's identity to a trust root (Trust Anchoring), and confirms the subject digest before trusting any claim. This closes the substitution gap from Layer 1: because the signed payload commits to the artifact digest, an attacker cannot repoint the entry to a different artifact or forge claims without the publisher's private key. Consumers that rely on trust metadata MUST verify signatures and MUST reject Trust Manifests whose signature does not validate, whose subject does not match the fetched artifact, or whose identity cannot be anchored.

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 SHOULD 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 binds the signed Trust Manifest to the artifact digest via subject, preventing both Trust Manifest forgery and artifact substitution under a valid signature.
• Layer 3 makes modification structurally impossible through content-addressing.

Trust Manifest Substitution

Because a Trust Manifest is a peer element of the catalog entry rather than part of the artifact, an attacker who can write the catalog document can attempt to substitute the artifact, the Trust Manifest, or both. This specification defends against substitution with three compounding mechanisms:

• Subject binding. A signed Trust Manifest MUST include a subject that commits to the artifact's media type and content digest (see Subject Binding). The artifact reference therefore cannot be changed without invalidating the signature.
• Trust anchoring. A signature is only meaningful once the signer's identity is anchored to a trust root established out of band (see Trust Anchoring); otherwise an attacker can sign a forged manifest with their own key.
• Catalog-level integrity. Per-entry signatures do not prevent an attacker from adding, removing, or reordering whole entries. Hosts SHOULD additionally provide catalog-level integrity, either by serving the catalog through a content-addressed channel (Layer 3) or by including a top-level catalog signature computed over the JCS-canonicalized [[RFC8785]] catalog document (excluding the signature member itself) and verified exactly as a Trust Manifest signature.

Identifier Typosquatting

Catalog entries are identified by URIs/URNs. An attacker can register identifiers similar to legitimate ones (e.g., urn:air:acme.com:agent:financ vs. urn:air:acme.com: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 type) 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 extensions fields.