spec: make Catalog Entry displayName optional (not required) (ADR 0016)

[tadasant]

What this proposes

Make displayName OPTIONAL on the Catalog Entry rather than required — i.e. move it from the required members of a Catalog Entry (ai-catalog.md §Catalog Entry) into the OPTIONAL members, drop it from the Minimal Catalog (Level 1) conformance requirement, and add guidance that it SHOULD be set only when the referenced artifact does not already carry its own canonical human-readable name.

The intent: when an entry points at an artifact that names itself (an A2A Agent Card, an MCP Server Card), the artifact is the single source of truth and the entry shouldn't duplicate the name. When an entry points at something opaque that has no embedded name (a raw dataset, a model blob, a skill bundle), the entry is the only place a human-readable name can live — so the field stays available for exactly that case.

This change deliberately does not touch displayName on the HostInfo or Publisher objects — those name the catalog host and the publishing org respectively, which is genuinely catalog-authored metadata with no other home.

Alternative considered: removing the field entirely

My first instinct was to remove displayName from the entry level altogether and always defer to the artifact, but I'm not suggesting it because that would mean opaque artifacts have nowhere else to put a name. examples/ai-catalog.json has an application/parquet dataset entry; a Parquet file, a model blob, or a skill .zip doesn't embed a self-describing display name the way a card does. Removing the field outright would leave those artifacts nameless in a catalog. So "optional, with guidance" is the proposal; "remove entirely" is the rejected alternative.

Why make it optional — the duplication / drift problem

A Catalog Entry already points at the full artifact via url or data. For the card-shaped artifact types this spec calls out by media type, the human-readable name is already present in the artifact itself:

• A2A Agent Card — name is a REQUIRED, human-readable field. From the A2A protobuf spec (specification/a2a.proto, message AgentCard):

  // A human readable name for the agent.
  // Example: "Recipe Agent"
  string name = 1 [(google.api.field_behavior) = REQUIRED];

• MCP Server Card — already carries a human-readable display name. In the Server Card schema, name is a reverse-DNS machine identifier (^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$), while title is documented as "Optional human-readable title or display name for the MCP server", and description (required) is human-readable too.

So for the two flagship artifact types, requiring displayName on the entry means every catalog publisher copies a value that already exists in the document the client is about to fetch, and then has to keep the two in sync forever. When they drift — and over time they will — a consumer has two conflicting human-readable names for the same thing and no principled way to pick. Making the field optional (and recommending omission for self-naming artifacts) keeps the name fresh and authoritative at its source, while the entry stays a thin pointer.

What's in the diff

• Normative: displayName moved from required → OPTIONAL members, with a SHOULD-guidance paragraph (set it only when the artifact has no canonical name; omit it for self-naming cards; the artifact's own name wins on conflict). Removed from the Minimal Catalog (Level 1) required-at-minimum list.
• Examples (all of them, for internal consistency): card-backed entries (A2A cards, MCP Server Cards, registry server.json, plugin manifests) now omit displayName; opaque entries (the application/parquet dataset, application/agentskill+zip skill bundles) and nested application/ai-catalog+json entries — which have no embedded canonical name — keep it. HostInfo/Publisher displayName untouched. The field still exists, so the class diagram and the "logical format" vocabulary lists are unchanged.
• Conceptual-mapping tables (MCP registry, Claude plugins) updated so the human-readable name maps to the artifact, with entry displayName framed as the fallback for nameless artifacts.

Some history (for transparency)

As far as I can reconstruct from the public record, displayName was required from its first appearance rather than as the outcome of an explicit "should this be mandatory?" debate:

• It entered the draft as name in commit 0271c14 (2026-03-31), already under "It MUST contain the following members."
• It was renamed name → displayName in 1e8c70c9 per the AI Actor Naming Standard (PR #19), still required, and shipped via PR #27.

I went looking for a written rationale for the mandatory status specifically — across the ADRs (0001–0013), issues, and discussions — and couldn't find one. The closest articulations of the field's purpose are PR #19 ("a human-readable name used for discovery in UIs … not required to be unique") and ADR 0013 framing the catalog as "the authoring and discovery format — a human-readable JSON document." I might simply be missing the discussion where requiring it was decided — if there's prior context I've overlooked, please point me to it, since it likely bears directly on the tradeoff.

Counter-argument to landing this

The strongest argument I can construct for keeping it required is browsing UX: a UI that renders a list of N artifacts shouldn't have to fetch N separate cards just to show names, so requiring displayName on the entry makes the catalog self-describing for a cheap list view.

However, that's a steep trade-off for a permanent duplication/sync cost; one we'd like to avoid making on the MCP side. I'm not sure I'm convinced that UIs of AI Catalogs will be a major use case of AI Catalog (please correct me if you foresee otherwise, would love to understand the use case), and the optional form still lets a publisher populate displayName on every entry if they want the self-describing list view. It just doesn't force the card-backed entries to carry a redundant copy.

If there's a use case beyond browsing that makes the field load-bearing enough to mandate, would love to understand.

[darrelmiller]

My perspective on this is that with the identifier and description property, a registry can synthesize a friendly display name for their registry. Picking the last segment of the URN identifier would likely be a reasonable substitute

[mindpower]

Agree that for browsing/indexing, the displayName is useful to avoid the traffic to the A2A/MCP service, but it doesn't need to be a mandatory field. Making it optional makes perfect sense and should work well.