feat: AIP-143 – Standardized codes - #24
Conversation
Sorry, something went wrong.
| ## Guidance | ||
|
|
||
| For concepts where a standardized code exists and is in common use, fields | ||
| representing these concepts **should** use the standardized code for both input |
There was a problem hiding this comment.
- @Alfus The important part here is that the string itself is the immutable, canonical code, and is used on the wire format. You do not need to create a separate enum, and if you do, then you fall out of synchronization quickly.
- @hudlow What this does bring to mind is that we validate that enums are lower snake strings. But this guidance correctly says, do not bastardize canonical codes into lower snake.
- @lukesneeringer It sounds like the IBM linter needs an exception here, allowing industry standard formats.
Sorry, something went wrong.
There was a problem hiding this comment.
@hudlow Perhaps a specific note about not bastardizing strings into a company's string enum format.
Sorry, something went wrong.
|
|
||
| - Fields representing standardized concepts **must** use the appropriate data | ||
| type for the standard code (usually `string`). | ||
| - Fields representing standardized concepts **should not** use enums, even if |
There was a problem hiding this comment.
Maybe distinguish the OpenAPI "choices" concept here.
Sorry, something went wrong.
| case-insensitive unless this would introduce ambiguity (for example, accept | ||
| both `en-gb` and `en-GB`). When providing values to users, APIs **should** | ||
| use the canonical case (in the example above, `en-GB`). | ||
|
|
There was a problem hiding this comment.
Maybe add a quick section about defaults, saying that defaults are permissible, and the sentinel value must be empty.
Sorry, something went wrong.
mkistler
left a comment
There was a problem hiding this comment.
Looks good! 👍
Sorry, something went wrong.
No description provided.