From afb35c964c09c4e7c08f41f284df3e8ccb7f432b Mon Sep 17 00:00:00 2001 From: Yusuke Tsutsumi Date: Sat, 6 May 2023 13:23:28 -0700 Subject: [PATCH 1/2] feat(AIP-123): require singular and plural Requiring singular and plural annotations on resources can enable new use cases in code generation and documentation, and prevents incorrect inferences about these values from the resource type. See https://github.com/googleapis/api-linter/issues/722 for additional discussion around the usage of singular and plural. --- aip/general/0123.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/aip/general/0123.md b/aip/general/0123.md index b2d84f09b1..81d237ba09 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. @@ -78,6 +80,8 @@ message Topic { - 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. +- Plural **must** be the lower camel case plural of the singular. #### Pattern uniqueness @@ -92,6 +96,16 @@ 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 @@ -102,6 +116,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. From e4be5cb03f7acf18f7997c1e063eb293f7562928 Mon Sep 17 00:00:00 2001 From: Yusuke Tsutsumi Date: Tue, 9 May 2023 15:37:31 -0700 Subject: [PATCH 2/2] addressing feedback - moving singular / plural pattern guidance as nested bullets. --- aip/general/0123.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/aip/general/0123.md b/aip/general/0123.md index 81d237ba09..00433e2240 100644 --- a/aip/general/0123.md +++ b/aip/general/0123.md @@ -77,11 +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 @@ -109,6 +111,7 @@ 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