feat(spec): add ADR-0021 to support multiple identities via alsoKnownAs

[ramizpolic]

Summary

This PR resolves #52 (support for multiple identities per artifact) by adding an
OPTIONAL alsoKnownAs member to the Trust Manifest, following the approach
favored in the issue discussion and AI Catalog meeting over an identities[] array.

Real artifacts frequently hold more than one verifiable identity at the same
time, for example a SPIFFE ID for runtime workload identity and a DID for
publisher-anchored organizational identity. Today there is no first-class
place to declare them, forcing publishers to embed secondary identities
through attestations[] or metadata, where consumers cannot discover or
verify them.

Changes Included

1. Added ADR-0019: Documents the decision to declare alternative identities
   through an alsoKnownAs URI array inside the Trust Manifest (rather than
   on the Catalog Entry), so aliases are covered by the existing manifest
   signature and remain verifiable through the trust bundle.
2. Updated ai-catalog.md:
   • Added the alsoKnownAs member to the Trust Manifest optional members,
     with normative rules (canonical identity, no duplicates,
     domain-alignment applies only to identity).
   • Added a "Verifying Alternative Identities" verification procedure:
     verifying the manifest signature verifies every listed alias, no
     per-alias proof mechanism is required.
   • Updated the CDDL schema, data model diagram, and examples.

Motivation

Consumers can programmatically discover and pin alternate identities of the
same subject using whichever identity scheme their tooling resolves, while
identity remains the single canonical identifier for referencing and
equivalence checking. Because alsoKnownAs lives inside the signed manifest
content, no new signing mechanism is needed and the field is tamper-proof
under the catalog-poisoning threat model.

[github-actions]

Preview: https://ai-catalog.io/pr/91/spec/

This comment is updated automatically while the pull request preview is available.

[kthota-g]

I feel there is inconsistency with type discovery for identity and alsoKnownAs. For identity, publishers can provide an explicit identityType hint. But for alsoKnownAs, the consumers are forced to rely on inferring the type from URI scheme. At least I felt there is a mismatch between identityType and alsoKnownAs looking at the manifest.

If we don't want to remove identityType or introduce identityType per alias, probably explicitly define that identityType is a type hint only for identity attribute.

[ramizpolic]

thanks for raising this @kthota-g. i have patched the spec to include details around type inference for alias identities, hope it addresses your concerns.

[darrelmiller]

@ramizpolic Can you clarify why we don't need identityType?

Can we also clarify if the purpose is both to be an alternative identify, and a record of a rename. i.e. the "alsoKnownAs" includes "formerlyKnownAs".

[yangbaechu]

The example's consumer can't resolve the canonical SPIFFE ID, but key resolution is based on identity. So it can't verify the signature the alias depends on. Would a case where identity resolves fit better?

[ramizpolic]

Good catch, thanks @yangbaechu! Added a fix to the spec to state explicitly that signature verification always resolves the key from the canonical identity (so a consumer that can't resolve it can't rely on any alias) and patched the examples.

[jdamick]

This is something that would be valuable to my use case. We would like to have the flexibility to issue a DID and SPIFFE id. There different preferences depending on the use and who is using the ai-catalog that may require DID or SPIFFE and I've heard requests for each.

[jdamick]

does this need a type or at least the possibility of a type?

Perhaps:

"alsoKnownAs" : [
  { 
   "identity": "did:web:acme-corp.com:agent:finance",
   "identityType": "did:web",
  }
]

[ramizpolic]

Thanks for raising this @jdamick. I patched the spec to use an array of Identity Alias objects mirroring the canonical identity/identityType pair. This also covers your use case as consumers can pick the alias by explicit type rather than inferring from schemes (which is not always possible as described in #91 (comment)).

[ramizpolic]

@ramizpolic Can you clarify why we don't need identityType?

Can we also clarify if the purpose is both to be an alternative identify, and a record of a rename. i.e. the "alsoKnownAs" includes "formerlyKnownAs".

Good points @darrelmiller, addressed both of the questions in the spec:

• identityType: we now have it per alias since pure scheme inference was ambiguous for schemes shared by multiple identity types (e.g., an https: URI could be a JWK Set or a did:web equivalent)
• renames: patched the spec to include notes about former identifiers, preserving continuity after a rename or migration between identities and schemes

[Wolfe-Jam]

Proposal: Registry-scoped identity + alsoKnownAs together solve both determinism and flexibility.

The Pattern:

Make identity deterministic from registry. Let artifacts declare schemes within each registry:

Registry 1 (ai-catalog.io):
  Canonical: ai-catalog.io/anthropic/finance-agent
  alsoKnownAs: ["did:web:anthropic.com/finance-agent", "spiffe://anthropic.com/finance"]

Registry 2 (other-registry.io):
  Canonical: other-registry.io/anthropic/finance-agent
  alsoKnownAs: ["did:web:anthropic.com/finance-agent", "spiffe://anthropic.com/finance"]

Same artifact, different canonical identities per registry. Within each, the artifact declares which schemes it recognizes.

Why Together:

• alsoKnownAs alone: Identity floats free; consumers don't know which registry is canonical.
• Registry-scoped alone: Loses flexibility for multi-scheme artifacts.
• Both: Canonical identity is deterministic (registry-bound). Aliases are flexible (publisher-signed). Threat models align — registry proves canonical, manifest proves schemes.

Media-Types are definitive, yet No Media-Types Required:

You don't need IANA registration to implement registry-scoped identity. You need:

1. One registry of truth per artifact class
2. Canonical identity scoped by registry + namespace
3. Aliases declared within, signed by publisher (your ADR-0021)

Lower bar, same problem solved.

[jdamick]

Proposal: Registry-scoped identity + alsoKnownAs together solve both determinism and flexibility.

The Pattern:

Make identity deterministic from registry. Let artifacts declare schemes within each registry:

I'm not sure I understand this proposal because the entries or the trustManifest have the identifier, not the registry. Why would you promote the identifier to the registry level? I don't see how that addresses what is being discussed here?

[Wolfe-Jam]

You're right. The trustManifest has the identifier; the signature covers it. alsoKnownAs with manifest signature already solves the multi-scheme problem. I was proposing a registry-level constraint where you already have one.

[kthota-g]

An artifact's identity has no bearing on the catalog that's hosted in. For example: A finance-agent published by acme.com and its trustManifest.identity would remain the same across any catalogs/registries and consumers can verify just the artifact's identity based on the trustManifest.

Although catalog host's identity itself can be verified via host.identifer.