--- a/base/rendered.txt +++ b/head/rendered.txt @@ -298,6 +298,21 @@ description A string containing a short description of the artifact. +This field SHOULD be set only when the referenced artifact does not +already carry its own canonical description — for example a raw +dataset (application/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. tags @@ -309,6 +324,21 @@ 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 (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. updatedAt @@ -363,6 +393,29 @@ the identifier segment in step 3. A publisher MAY still set displayName on such an entry to provide a better name than the bare identifier segment. + +Resolving an Artifact's Description + +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. + +The referenced artifact's own canonical description, if the +consumer has already fetched or cached the artifact — for example the +description field of an A2A Agent Card or of an MCP Server Card. + +No description, if neither is available. Consumers SHOULD render +the entry gracefully without one. + +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. Multi-Version Entries @@ -1963,11 +2016,11 @@ description -Entry description +Stays in the artifact; entry description is omitted unless the artifact lacks one (same authoritative-source rule as title/displayName) version -Entry version +Stays in the artifact; entry version is omitted for a single entry, but is set (and MUST match the artifact) when the catalog lists multiple versions of the same identifier repository @@ -2299,7 +2352,7 @@ Plugin description -Entry description +Stays in the plugin manifest; entry description is omitted unless the manifest lacks one (same authoritative-source rule as the plugin name) Plugin category