Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(AIP-123): require singular and plural #1091

Merged
merged 3 commits into from
May 9, 2023
Merged

feat(AIP-123): require singular and plural #1091

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
afb35c9
feat(AIP-123): require singular and plural
toumorokoshi May 6, 2023
fd2a8c9
Merge branch 'master' into toum/singular-plural
toumorokoshi May 9, 2023
e4be5cb
addressing feedback
toumorokoshi May 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 20 additions & 2 deletions aip/general/0123.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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

Expand All @@ -92,16 +98,28 @@ 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.

<!-- prettier-ignore-start -->
[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
<!-- prettier-ignore-end -->

## 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.
Expand Down