diff --git a/aip/general/0123.md b/aip/general/0123.md index 70d9a3e59..c66e20093 100644 --- a/aip/general/0123.md +++ b/aip/general/0123.md @@ -42,6 +42,9 @@ the following pattern: `{Service Name}/{Type}`. The type name **must**: - Be of the singular form of the noun. - Use PascalCase (UpperCamelCase). +Additionally APIs **should** avoid overly generic resource names like +`Metadata`, `Resource`, `Config`, `Settings`, etc. + ### Examples Examples of resource types include: @@ -108,6 +111,13 @@ 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. +### Overly Generic Type Names + +Overly generic types like `Metadata` or `Resource` will cause confusion as the +API introduces more concepts. Unless the resource represents a +[singleton][aip-156] containing API-level settings, a more specific name should +be used. + [aip-122]: ./0122.md [API Group]: https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-groups @@ -118,7 +128,7 @@ such as UpperCamelCase and snake_case. ## Changelog - +- **2023-12-20**: Added guidance on overly-generic resource type names. - **2023-09-19**: Prohibit duplicate pattern variables. - **2023-05-06**: Adding requirement of singular and plural. - **2023-01-28**: Clarifying guidance for the resource type name.