diff --git a/aip/general/0123.md b/aip/general/0123.md index 33f660658..448dd5e19 100644 --- a/aip/general/0123.md +++ b/aip/general/0123.md @@ -28,15 +28,15 @@ In the guidance below, we use the following terms: This usually (but not necessarily) matches the hostname that users use to call the service. Example: `pubsub.googleapis.com`. This is equivalent to an [API Group][] in Kubernetes. -- **Type:** This is the name used for the type within the API. This *should* - match the name of the protobuf message. This is equivalent to an [Object][] in - Kubernetes. +- **Type:** This is the name used for the type within the API e.g. the name of + the Protobuf `message`. This is equivalent to an [Object][] in Kubernetes. ## Guidance APIs **must** define a resource type for each resource in the API, according to the following pattern: `{Service Name}/{Type}`. The type name **must**: +- Match the containing API type's name. - Start with an uppercase letter. - Only contain alphanumeric characters. - Be of the singular form of the noun. @@ -104,6 +104,15 @@ resource: ## Rationale +### Type and message name alignment + +In addition to simple schema-resource coherence and alignment, a number of +consumers benefit from the `{Type}` and `message` names matching. Consumers have +simpler lookups, client libraries get the same in addition to aligned user +experience where resource-oriented code has naming aligned with the generated +`message` code, generated reference documentation aligns resources with +`message` docs, etc. + ### Singular and Plural Well-defined singular and plurals of a resource enable clients to determine the @@ -124,6 +133,7 @@ such as UpperCamelCase and snake_case. ## Changelog +- **2025-01-09**: Strongly align resource type and message naming. - **2024-08-07**: Added multi-pattern ordering compatibility requirements. - **2023-09-19**: Prohibited duplicate pattern variables. - **2023-05-06**: Added requirement of singular and plural.