diff --git a/aip/general/0123.md b/aip/general/0123.md index b2d84f09b1..00433e2240 100644 --- a/aip/general/0123.md +++ b/aip/general/0123.md @@ -63,6 +63,8 @@ message Topic { option (google.api.resource) = { type: "pubsub.googleapis.com/Topic" pattern: "projects/{project}/topics/{topic}" + singular: "topic" + plural: "topics" }; // The resource name of the topic. @@ -75,9 +77,13 @@ message Topic { - Patterns **must** correspond to the [resource name][aip-122]. - Pattern variables (the segments within braces) **must** use `snake_case`, and **must not** use an `_id` suffix. -- Pattern variables **must** be the singular form of the resource type e.g. the - pattern variable representing a `Topic` resource ID is named `{topic}`. - Pattern variables **must** conform to the format `[a-z][_a-z0-9]*[a-z0-9]`. +- Singular **must** be the lower camel case of the type. + - Pattern variables **must** be the singular form of the resource type e.g. + a pattern variable representing a `Topic` resource ID is named `{topic}`. +- Plural **must** be the lower camel case plural of the singular. + - Pattern collection identifier segments **must** match the plural of the + resources, except in the case of [nested collections][]. #### Pattern uniqueness @@ -92,9 +98,20 @@ resource: - `user/{user}` - `user/{user_part_1}~{user_part_2}` +## Rationale + +### Singular and Plural + +Well-defined singular and plurals of a resource enable clients to determine the +proper name to use in code and documentation. + +lowerCamelCase can be translated into other common forms of a resource name +such as UpperCamelCase and snake_case. + [aip-122]: ./0122.md [API Group]: https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-groups +[nested collections]: ./0122.md#collection-identifiers [Object]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#types-kinds [resource]: https://github.com/googleapis/googleapis/blob/master/google/api/resource.proto [service configuration]: https://github.com/googleapis/googleapis/blob/master/google/api/service.proto @@ -102,6 +119,7 @@ resource: ## Changelog +- **2023-05-06**: Adding requirement of singular and plural. - **2023-01-28**: Clarifying guidance for the resource type name. - **2022-10-28**: Added pattern variable format guidance. - **2020-05-14**: Added pattern uniqueness.