Skip to content

feat(spec): add Deployment official extension (resolves #64) - #96

Open
marianogonzalez wants to merge 1 commit into
Agent-Card:mainfrom
marianogonzalez:feat/deployment-metadata-extension
Open

feat(spec): add Deployment official extension (resolves #64)#96
marianogonzalez wants to merge 1 commit into
Agent-Card:mainfrom
marianogonzalez:feat/deployment-metadata-extension

Conversation

@marianogonzalez

Copy link
Copy Markdown

Summary

This PR resolves #64
(structured deployment metadata) by adding an official extension
https://ai-catalog.org/extensions/deployment — rather than a native
instances field on the Catalog Entry as the original proposal suggested.

A Catalog Entry conflates identity ("what the artifact is") with instance
("where it lives"). The same logical agent or server is routinely deployed
many times — across environments (development, staging, production), across
release channels (stable, beta, LTS, edge), and across regions (us-east-1,
eu-west-1) whose data-residency and compliance constraints differ. The
entry's identifier and top-level url capture the artifact and its default
entry point but cannot express these deployments. The extension lets a
publisher enumerate them on an entry so a consumer can deterministically
select an instance that satisfies its policy — an EU client targeting a GDPR
instance in eu-west-1, a test harness targeting staging, or a client
opting into a beta release channel — while the entry keeps a single logical
identity.

Because the extension is additive and unrecognized extensions keys are
ignored, it needs no specVersion change — a catalog carrying it remains
a conformant 1.0 document.

Changes Included

  1. adr/0022-deployment-metadata-extension.md (new) — records the
    decision to implement Spec Proposal: Deployment metadata #64 as an official extension rather than a native
    entry field, consistent with the closed-core philosophy of
    ADR-0012.
  2. specification/ai-catalog.md:
    • Registered the extension in the Official Extensions list alongside
      metadata.
    • Added the Deployment Metadata Extension section: value structure
      (a REQUIRED, non-empty instances[] array), the Instance object
      (instanceId and url REQUIRED; environment, releaseChannel,
      region, dataResidency, compliance, description OPTIONAL),
      selection semantics with a no-unsafe-fallback rule, and an example.
    • Added an informative CDDL block for the extension value.
    • Added a Privacy Considerations note on infrastructure-topology
      disclosure and unsigned producer assertions.
  3. Developer docs — a new annotated example
    (docs/examples/deployment-metadata.md), an authoring section in
    Creating a Catalog, an instance-selection section in Consuming
    Catalogs
    , plus cross-links and a nav entry.

Reconciling the original proposal

The proposal in #64 predates several current conventions; the extension uses
today's forms:

Proposal (outdated) This PR (current)
urn:ai:… urn:air:{publisher}:{namespace}:{name} (ADR-0015)
native instances field on the entry official extensions entry (keeps the core schema closed)
compliance as a bare string ("GDPR") compliance as a string array, matching dataResidency and allowing multiple regimes
"canary" discovery environment (dev/staging/production) kept distinct from a new releaseChannel track (stable/beta/LTS/edge), since canary is a release strategy, not an environment tier

Design notes

  • Identity vs. instance. Every instance is an alternative endpoint for the
    same identifier; instances are deployments, not distinct artifacts. The
    entry's top-level url remains the default entry point, and one instance
    url SHOULD equal it so the default is represented among the instances.
  • environment and releaseChannel are orthogonal. environment
    describes where a version runs; releaseChannel describes the maturity
    track of the deployed version. Keeping them separate avoids overloading
    environment with release-strategy values.
  • Deployment metadata is not a trust control. dataResidency and
    compliance are unsigned producer assertions unless carried in a signed
    Trust Manifest; a consumer that needs assurance MUST corroborate them via
    attestations, not via this extension.
  • No unsafe fallback. A consumer that understands the extension MAY select
    an instance matching its policy; if none matches it SHOULD treat the
    artifact as unavailable for that request rather than fall back to a
    non-conforming instance — an EU-only client never silently uses a non-EU
    deployment.

Interoperability impact

No change to interoperability expectations for existing catalogs. The core
schema, CDDL for core types, conformance levels, and specVersion are all
unchanged; a consumer that does not implement the extension ignores it without
error, exactly as for any unrecognized extensions key.

Non-goals

  • A deployment resolver / load balancer or health-checking behavior — this
    is discovery metadata only; the entry's url and each instance url remain
    ordinary references.
  • Promoting deployment metadata to a core field — deliberately kept an
    extension per ADR-0012 / ADR-0022.
  • Treating compliance / dataResidency as enforceable guarantees
    they are producer assertions, verified (when needed) through the Trust
    Manifest.

Validation

  • uv run --locked python tools/build_spec.py specification/ai-catalog.md dist/index.html --config specification/respec-config.json — passes.
  • uv run --python 3.12 --locked --group docs mkdocs build --strict — passes, no broken links.
  • All deployment-bearing JSON examples validated.

Implement the deployment-metadata proposal from issue Agent-Card#64 as an official
extension keyed by https://ai-catalog.org/extensions/deployment, rather than
a native entry field. An entry's extensions map may carry a non-empty
instances[] array describing the concrete deployments of a single logical
artifact, enabling policy-aware instance selection while the entry keeps
one identity.

Each instance carries a required instanceId and url, plus optional
environment, releaseChannel (release maturity track, e.g. stable/beta/LTS/
EDGE, orthogonal to environment), region, dataResidency, compliance, and
description. Identifiers use the current urn:air format (ADR-0015).

- spec: Official Extensions entry, Deployment Metadata Extension section,
  informative CDDL, and privacy note
- adr: ADR-0021 documenting the official-extension decision
- docs: new deployment-metadata example (+ nav), creating/consuming guides

Signed-off-by: marianogonzalez <mariano.gonzalez@salesforce.com>
@marianogonzalez
marianogonzalez requested a review from a team as a code owner August 6, 2026 15:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Spec Proposal: Deployment metadata

1 participant