--- a/base/index.html +++ b/head/index.html @@ -328,14 +328,45 @@ Resolving an Artifact's Display Name for the full consumer resolution order.
descriptionapplication/parquet), a model blob, or a skill bundle
+ (application/agent-skills+zip), none of which embed a self-describing
+ description. When the referenced artifact does carry one — for example
+ the description field of an A2A Agent Card or of an MCP Server Card —
+ that artifact is the authoritative source and description SHOULD be
+ omitted to avoid duplicating a value that can drift out of sync. When
+ description 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 description carried by the referenced
+ artifact. Setting description is how a publisher deliberately provides
+ a listing-specific blurb in place of the artifact's own. See
+ Resolving an Artifact's Description
+ for the full consumer resolution order.tagsversionA string containing the version of this artifact.
Semantic Versioning is RECOMMENDED but not
required. See Multi-Version Entries for
- how versions interact with identifier.
identifier.
+Like displayName and description, version can restate a value the
+referenced artifact already carries (for example the version field of
+an A2A Agent Card or an MCP Server Card). For a single entry whose
+artifact carries its own version, version merely duplicates that value
+and SHOULD be omitted to avoid drift — a consumer can read the version
+from the artifact. Unlike displayName and description, however,
+version is not merely cosmetic: it is part of the entry's uniqueness
+key and consumers sort on it, so when a catalog lists multiple versions
+of the same identifier it is REQUIRED on those entries (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.
updatedAtidentifier segment in step 3. A publisher MAY still set
displayName on such an entry to provide a better name than the bare
identifier segment.
+
+Because description is OPTIONAL, a consumer rendering a catalog entry
+cannot assume it is present. To obtain a description, a consumer SHOULD
+resolve one in the following order:
description on the entry, if present. A publisher-supplied
+ description always wins, even when it differs from a description
+ carried by the referenced artifact.description field of an A2A Agent Card or of an MCP Server Card.As with a name, a consumer SHOULD NOT dereference an artifact at render +time solely to obtain a description. A registry, directory, or other +service built on top of a catalog SHOULD resolve the description once at +ingestion — alongside any other derived metadata it caches — rather than +fetching artifacts on the rendering path.
descriptiondescriptiondescription is omitted unless the artifact lacks one (same authoritative-source rule as title/displayName)versionversionversion is omitted for a single entry, but is set (and MUST match the artifact) when the catalog lists multiple versions of the same identifierrepositorydescriptiondescriptiondescription is omitted unless the manifest lacks one (same authoritative-source rule as the plugin name)category