diff --git a/graph/GuidelinesGraph.md b/graph/GuidelinesGraph.md index e11c809a..bdc282dc 100644 --- a/graph/GuidelinesGraph.md +++ b/graph/GuidelinesGraph.md @@ -99,7 +99,9 @@ Following is a short summary of the most often used conventions. | :no_entry: **MUST NOT** use redundant words in names. | - **Right:** /places/{id}/**displayName** or /phones/{id}/**number**
- **Wrong:** /places/{id}/**placeName** or /phones/{id}/**phoneNumber** | | :warning: **SHOULD NOT** use brand names in type or property names. | - **Right:** chat
- **Wrong:** teamsChat
- **NOTE:** there is an exception for resources that *only* exist under the `/admin` root segment and the `/users/{userId}/settings` path. | | :warning: **SHOULD NOT** use acronyms or abbreviations unless they are broadly understood. | - **Right:** url or htmlSignature
- **Wrong:** msodsUrl or dlp | -| :heavy_check_mark: **MUST** use singular nouns for type names. | - **Right:** address
- **Wrong:** addresses | +| :heavy_check_mark: **MUST** use singular nouns for non-enum type names. | - **Right:** address
- **Wrong:** addresses | +| :heavy_check_mark: **MUST** use singular nouns for non-flags enum type names. | - **Right:** color
- **Wrong:** colors | +| :heavy_check_mark: **MUST** use plural nouns for flags enum type names. | - **Right:** diplayMethods
- **Wrong:** displayMethod | | :heavy_check_mark: **MUST** use plural nouns for collections (for listing type or collection properties). | - **Right:** addresses
- **Wrong:** address | | :ballot_box_with_check: **SHOULD** pluralize the noun even when followed by an adjective (a *postpositive*).| - **Right:** passersby or mothersInLaw
- **Wrong:** notaryPublics or motherInLaws | | **CASING** | | diff --git a/graph/patterns/enums.md b/graph/patterns/enums.md index 926864e0..080435af 100644 --- a/graph/patterns/enums.md +++ b/graph/patterns/enums.md @@ -131,3 +131,13 @@ With such enum, customers can select multiple values in a single field: `displayMethod = tip | alert` In cases where two properties want to use the same *conceptual* `EnumType`, but one property is a collection while the other is single-values, the model should define *two* separate `EnumType`s, one being a non-flags enum with a singular name and the other marked as a flags enum with its name being the plural form of the non-flags enum. + +#### Flag enum + non-flag enum + +There are occasions where one API will want to use a non-flag enum, but another API will want a flags enum. +For example, the `displayMethod` example above may have one API that is configuring which display methods to use, and another API which is configuring that particular display method. +In this case, the first API will want a flags enum, but the second API will want to only allow configuring one display method at a time, and will therefore prefer a non-flags enum. + +Two enum types should be defined, one as a flags enum and the other as a non-flags enum. +The flags enum should be named such that it is plural, and the non-flags enum should be named such that it is singular. +The two types should be kept in sync with each other.