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 type identifier and referencing or embedding an AI artifact.

Trust Manifest

A JSON object grouping one contributor's trust metadata about an AI artifact. The entry stores it in the trustManifests array. Its contributor identifies the party to whom the claims are attributed; its optional signature authenticates that contributor's claims.

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 four 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"
    },
    {
      "identifier": "urn:air:example.com:agent:productivity-plugin",
      "displayName": "Productivity Plugin",
      "type": "application/agent-plugins+zip",
      "description": "Tools for common productivity workflows.",
      "tags": ["productivity", "workflows"],
      "url": "https://plugins.example.com/productivity.zip"
    }
  ]
}

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 Signature object authenticating this catalog snapshot, as defined in Catalog Snapshot Coverage. Signer authentication alone does not establish authority to represent the catalog operator; see Catalog Authorization.

additionalSignatures

Reserved for future use. Producers SHOULD omit this member. Consumers MUST accept and ignore it regardless of its value. It is excluded from this catalog's signature payload; it establishes no endorsement in this version.

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.

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). Consumers that do not recognize an identifier scheme MUST treat the value as opaque. Identifier syntax alone does not verify publisher identity or establish trust. For open or federated systems, a globally unique absolute URI is RECOMMENDED. An artifact publisher that wants an entry identifier to be preserved when the artifact appears in other catalogs SHOULD use the AI Catalog-specific urn:air naming structure with its own domain in the {publisher} segment. A catalog operator incorporating an entry for the first time with a publisher-authorized urn:air identifier MUST preserve that identifier exactly.

urn:air Identifier 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, and Catalog Projection for identifiers assigned while projecting an existing Catalog Entry or source-system record.

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)
• application/agent-plugins+zip — an Agent Plugin bundle (ZIP archive)
• application/agent-plugins+gzip — an Agent Plugin 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, a skill bundle (application/agent-skills+zip), or an Agent Plugin bundle (application/agent-plugins+zip), none of which directly expose a self-describing name without processing the artifact. 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. An entry MAY include that version when it needs to be signed directly. 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.

digest

A string containing the artifact content digest in Digest Format. For url, hash the exact retrieved artifact bytes. For data, hash the UTF-8 JCS-canonicalized [[RFC8785]] JSON value. Inline data MUST satisfy JCS's input requirements for artifact verification to succeed. A digest alone does not authenticate its source; see Entry Release Coverage.

trustManifests

An array of Trust Manifest objects. Each manifest groups one contributor's claims about this artifact and can carry its own signature. A contributor's identity is attribution, not proof of authorship.

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. Only publisher-authorized urn:air identifiers receive a cross-catalog preservation requirement, as defined in Catalog Projection.

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.

Catalog Projection

A publisher-authorized urn:air identifier is one assigned by the artifact publisher or its authorized delegate, with the artifact publisher's domain in the {publisher} segment.

Catalog projection creates a Catalog Entry from either a source Catalog Entry in another AI Catalog or a source record in another system. When incorporating a projected entry for the first time, a catalog operator MUST select its identifier by applying these rules in order:

1. If the source contains a publisher-authorized urn:air identifier, the operator MUST preserve it exactly.
2. Otherwise, the operator MAY preserve a non-urn:air source identifier or replace it. Non-urn:air identifiers have no guaranteed portability across catalogs.
3. When assigning a new identifier, an operator that becomes the artifact publisher SHOULD use urn:air with its own domain in the {publisher} segment. An operator acting as an authorized delegate SHOULD use urn:air with the delegating publisher's domain in that segment. An operator that is neither the artifact publisher nor its authorized delegate MUST use a non-urn:air identifier under its own control.

Operating a catalog or aggregating an entry does not make its operator the artifact publisher. A catalog operator MUST NOT infer publisher authorization from the artifact's URL or an unsigned publisher field.

Adopting a different primary identifier after publication requires an explicit migration mechanism, which this specification does not define.

An identifier assigned by a catalog operator identifies the artifact, not a particular version or source record. It MUST remain stable across versions, source-coordinate changes, and retrieval-URL changes, and MUST NOT be reassigned to another artifact. The catalog operator and artifact publisher are distinct roles. The operator is the entity identified by the top-level host field when that field is present.

A catalog operator MAY retain replaced source identifiers or source-system coordinates. If retained, they SHOULD be stored in a namespaced entry extension. They do not participate in catalog uniqueness or establish publisher identity, trust, or equivalence with another identifier.

{
  "identifier": "https://registry.example/ids/artifacts/7bf4a8c2",
  "type": "application/a2a-agent-card+json",
  "url": "https://registry.example/apis/registry/v3/groups/payments/artifacts/fraud-agent",
  "publisher": {
    "identifier": "did:web:acme.example",
    "displayName": "Acme"
  },
  "extensions": {
    "com.example.registry.coordinates": {
      "registryUri": "https://registry.example",
      "sourceIdentifier": "foo",
      "namespace": "payments",
      "name": "fraud-agent"
    }
  }
}

The extension key is illustrative.

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").

Contributor Identity

contributor MUST be an absolute URI [[RFC3986]] identifying the contributor asserting this manifest's references or claims, not necessarily the issuer of every referenced attestation or provenance statement. Authors SHOULD use their existing identity URI, such as did:web:assessor.example. The value MUST be preserved exactly when forwarding a Trust Manifest. Consumers MUST NOT infer authentication from its spelling or mere presence.

A signed Trust Manifest's signature.signer MUST exactly equal contributor. Consumers MUST compare these decoded JSON strings case-sensitively, without URI normalization. Verifying the signature and this equality authenticates the contributor attribution. Accepting the claims for an entry additionally requires entry release binding. A signature over one manifest does not authenticate other manifests or other entry fields.

Independent Contributions and Updates

Contributors can publish and update their manifests without modifying other contributors' manifests or invalidating their signatures. This version supports one signer per manifest and defines no references between manifests.

An entry MAY contain multiple manifests from the same contributor, including manifests using different verification profiles. Array order does not imply trust or precedence. Consumers evaluate each manifest independently.

A contributor MAY publish an updated Trust Manifest for the same release. Two registries may retrieve that manifest at different times and hold different signed versions. When choosing among updates for the same contributor and release, consumers SHOULD prefer the manifest with the most recent acceptable signature, comparing authenticated issuedAt instants. An issuance time is the signer's assertion, not an independently trusted clock. Equal issuance times with different content require local selection policy; consumers MUST NOT infer an ordering from array order. Registries SHOULD preserve the chosen manifest and its signature rather than merge separately signed contents.

Manifest Validity

A Trust Manifest MUST contain at least one of: a signature, a trustSchema, a non-empty attestations array, a non-empty provenance array, or a non-empty extensions object. A manifest containing a signature MUST also contain subject. A signed manifest MAY endorse only the artifact release identified by that subject, without additional trust evidence. These members' presence does not establish verification. Empty manifests MUST be omitted.

Optional Members

subject

A Subject object identifying the artifact release and representation to which these claims apply. REQUIRED when signature is present. It lets the signed manifest travel independently of the entry.

signature

A Signature object authenticating this manifest's contents, including its subject and contributor identity.

additionalSignatures

Reserved for future use. Producers SHOULD omit this member. Consumers MUST accept and ignore it regardless of its value. It is excluded from this manifest's signature payload; it establishes no endorsement in this version.

trustSchema

A Trust Schema object describing the framework the contributor applies to its claims about this artifact. The descriptor does not itself establish a trust root or override the consumer's policy.

attestations

An array of Attestation objects carrying references to evidence. Their formats or applicable profiles define evidence verification.

provenance

An array of Provenance Link objects.

extensions

A JSON object containing this contributor's additional trust metadata, using the namespaced keys defined in Extensions. Entry extensions describe shared artifact metadata; manifest extensions express a particular contributor's claims. A manifest signature covers only the latter.

For example, this unsigned entry carries independent contributions:

{
  "identifier": "urn:air:acme.com:agent:finance",
  "type": "application/a2a-agent-card+json",
  "url": "https://acme.com/finance.json",
  "trustManifests": [
    {
      "contributor": "did:web:acme.com",
      "provenance": [{
        "relation": "publishedFrom",
        "sourceId": "https://github.com/acme/finance"
      }]
    },
    {
      "contributor": "did:web:assessor.example",
      "attestations": [{
        "type": "SOC2-Type2",
        "uri": "https://assessor.example/reports/acme.pdf"
      }]
    }
  ]
}

Subject Object

A Subject object binds a Trust Manifest to the artifact release it describes. It MUST contain:

identifier

A string containing the artifact's logical identifier. It MUST exactly equal the containing entry's identifier.

type

A string containing the artifact's type identifier. It MUST exactly equal the containing entry's type.

digest

The artifact content digest in Digest Format. It MUST exactly equal the containing entry's digest, which MUST be present when an entry carries a signed Trust Manifest. For url, hash the exact retrieved artifact bytes. For data, hash the UTF-8 JCS-canonicalized JSON value.

The following member is conditional:

version

A string containing the artifact release version. subject.version MUST be present exactly when entry.version is present, and its value MUST exactly equal entry.version.

These fields deliberately repeat entry values to make the signed manifest self-contained. Verification of a standalone manifest authenticates its subject and claims; accepting those claims for an entry additionally requires Entry Release Coverage. The subject does not include the retrieval URL, permitting mirrors serving identical artifact bytes.

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 Trust Manifests, catalog snapshots, and the evidence referenced by Trust Manifests. Verification is OPTIONAL — consumers that do not need trust assurance can skip this entirely.

The did:web Signer Profile defines an initial interoperable authentication mechanism. Other signer profiles can use the same data model. A signer profile MUST define permitted signer identities, key discovery and authorization, algorithms, JWS header requirements, validity checks, and any authority it establishes. Consumers MUST NOT authenticate an identity using an unsupported profile.

sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

{
  "contributor": "did:web:acme.com",
  "subject": {
    "identifier": "urn:air:acme.com:agent:finance",
    "type": "application/a2a-agent-card+json",
    "digest": "sha256:56bbd2ff730d81a52951fc2f58809dfb086b4be7a82766dcc18cfe32ff6acbbd"
  },
  "signature": {
    "signer": "did:web:acme.com",
    "profile": "did-web-v1",
    "issuedAt": "2026-09-12T10:00:00Z"
  }
}

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 trustManifests, 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.
2. Policy URLs (https://ai-catalog.org/extensions/policy-urls) - Links to the policies governing an artifact, defined below.

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.

{
  "extensions": {
    "https://ai-catalog.org/extensions/policy-urls": {
      "privacyPolicyUrl": "https://example.com/privacy",
      "termsOfServiceUrl": "https://example.com/terms"
    }
  }
}

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 carries a JSON media type (application/ai-catalog+json is preferred, but a generic type such as application/json is acceptable, per Location Independence) and the document 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 defined members are OPTIONAL. This level supports consumers that only need a simple list of artifacts. Each manifest in trustManifests, when present at any level, MUST satisfy 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 an acceptably signed, publisher-authorized Trust Manifest on each entry whose publisher authenticity is to be relied upon, using The did:web Publisher Profile.
• Consumers MUST authenticate signers, verify signatures and endorsement times, enforce Entry Release Coverage, and verify artifact content against entry.digest before relying on signed claims.
• Additional contributors MAY provide their own Trust Manifests. Before relying on their claims, consumers MUST verify each contributor's signature and the subject binding to the same entry release.
• Consumers MUST distinguish the initial interoperable did:web profiles from other profiles supported by private agreement. Future profiles can define additional interoperable authentication and authorization mechanisms.
• SHOULD provide catalog-level integrity through a content-addressed channel or a signature satisfying Catalog Snapshot Coverage and an applicable operator-authorization policy.
• MAY include signed attestations, provenance, and manifest extensions, according to consumer policy.

Conformance does not imply that every optional signature is acceptable or that every claim is true. Unverified additional contributions do not by themselves invalidate an independently verified publisher endorsement.

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 — Artifact Digest

entry.digest allows consumers to compare fetched or embedded content with the declared digest. Without an authenticated endorsement, an attacker controlling the catalog can substitute both the content and the digest. A provenance source digest describes the source, not the entry's representation.

Layer 2 — Trust Manifest Signatures

A manifest signature binds its complete claims to the artifact identifier, version when present, type, and digest through its signed subject. The consumer authenticates its signer, checks release coverage, verifies artifact integrity, and evaluates authority for the intended claim. Independent contributor manifests can coexist. A valid signature over one contribution does not authenticate another or establish completeness of the catalog.

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 logical artifact release and its representation via the signed subject, preventing artifact substitution or relabeling 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:

• Release binding. Every accepted artifact endorsement jointly covers subject identifier, type, digest, and version when present, plus the claims relied upon. Consumers check subject-to-entry equality as well as cryptography and artifact bytes.
• Signer and claim authority. Contributor identities are not proof. Publisher authorization requires the authenticated signer to match the publisher namespace; contributor attribution requires authentication as that contributor. An attacker's signature under its own identity does not authenticate another publisher or contributor.
• Catalog-level integrity. Manifest signatures do not prevent adding, removing, or reordering complete entries. Hosts SHOULD provide a signature satisfying Catalog Snapshot Coverage, with operator authorization, or an authenticated content-addressed channel.

Signatures do not prove that a newer manifest, omitted contributor, or revoked evidence does not exist. Consumers requiring freshness beyond acceptable endorsement times need an appropriate update source and evidence policy.

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 acceptable contributor endorsement times; unsigned entry updatedAt is only an advisory listing timestamp.
• 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.