-
Notifications
You must be signed in to change notification settings - Fork 3
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.
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-143 – Standardized codes #24
base: main
Are you sure you want to change the base?
Conversation
## 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- @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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@hudlow Perhaps a specific note about not bastardizing strings into a company's string enum format.
aip/general/0143/aip.md
Outdated
|
||
- 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe distinguish the OpenAPI "choices" concept here.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe add a quick section about defaults, saying that defaults are permissible, and the sentinel value must be empty.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good! 👍
No description provided.