-
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-140 – Field names #33
Open
lukesneeringer
wants to merge
3
commits into
main
Choose a base branch
from
aip-140
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -0,0 +1,148 @@ | ||||||
# Field names | ||||||
|
||||||
Naming fields in a way that is intuitive to users can often be one of the most | ||||||
challenging aspects of designing an API. This is true for many reasons; often a | ||||||
field name that seems entirely intuitive to the author can baffle a reader. | ||||||
|
||||||
Additionally, users rarely use only one API; they use many APIs together. As a | ||||||
result, a single company using the same name to mean different things (or | ||||||
different names to mean the same thing) can often cause unnecessary confusion, | ||||||
because users can no longer take what they've already learned from one API and | ||||||
apply that to another. | ||||||
|
||||||
In short, APIs are easiest to understand when field names are simple, | ||||||
intuitive, and consistent with one another. | ||||||
|
||||||
## Guidance | ||||||
|
||||||
Field names **should** be in correct American English. | ||||||
|
||||||
Field names **should** clearly and precisely communicate the concept being | ||||||
presented and avoid overly general names that are ambiguous. That said, field | ||||||
names **should** avoid including unnecessary words. In particular, avoid | ||||||
including adjectives that always apply and add little cognitive value. For | ||||||
example, a `proxy_settings` field might be as helpful as | ||||||
`shared_proxy_settings` if there is no unshared variant. | ||||||
|
||||||
### Case | ||||||
|
||||||
Field definitions **must** use the appropriate case for the IDL being used | ||||||
(`camelCase` for TypeScript, `lower_snake_case` for protocol buffers, and so | ||||||
on). These names **should** be mapped to an appropriate naming convention in | ||||||
JSON and in generated code. | ||||||
|
||||||
Additionally, each word in the field **must not** begin with a number, because | ||||||
it creates ambiguity when converting between snake case and camel case. | ||||||
Similarly, snake case fields **must not** contain leading, trailing, or | ||||||
adjacent underscores. | ||||||
|
||||||
### Consistency | ||||||
|
||||||
APIs **should** endeavor to use the same name for the same concept and | ||||||
different names for different concepts wherever possible. This includes names | ||||||
across multiple APIs, in particular if those APIs are likely to be used | ||||||
together. | ||||||
|
||||||
### Array fields | ||||||
|
||||||
Array fields **must** use the proper plural form, such as `books` or `authors`. | ||||||
On the other hand, non-array fields **should** use the singular form such as | ||||||
`book` or `author`. | ||||||
|
||||||
### Prepositions | ||||||
lukesneeringer marked this conversation as resolved.
Show resolved
Hide resolved
lukesneeringer marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
||||||
Field names **should not** include prepositions (such as "with", "for", "at", | ||||||
"by", etc). For example: | ||||||
|
||||||
- `error_reason` (**not** `reason_for_error`) | ||||||
- `author` (**not** `written_by`) | ||||||
|
||||||
There are several reasons for this: | ||||||
|
||||||
- It is easier for field names to match more often when following this | ||||||
convention. | ||||||
- Spoken languages vary widely in their conjugation rules, and avoiding | ||||||
prepositions tends to lead to more natural translation for many speakers for | ||||||
whom English is a secondary language (generally at no cost to Anglophones). | ||||||
- Additionally, prepositions in field names may also indicate a design concern, | ||||||
such as an overly-restrictive field or a sub-optimal data type. This is | ||||||
particularly true regarding "with": a field named `book_with_publisher` | ||||||
likely indicates that the book resource may be improperly structured and | ||||||
worth redesigning. | ||||||
|
||||||
**Note:** The word "per" is an exception to this rule, particularly in two | ||||||
cases. Often "per" is part of a unit (e.g. "miles per hour"), in which case the | ||||||
preposition must be present to accurately convey the unit. Additionally, "per" | ||||||
is often appropriate in reporting scenarios (e.g. "nodes per instance" or | ||||||
"failures per hour"). | ||||||
|
||||||
### Mood | ||||||
|
||||||
Field names **should** use the imperative mood ("enable", "import") when the | ||||||
user is deciding what to do, and the declarative mood ("enabled", "imported") | ||||||
when reporting on the state of the system. If the same field is used for both | ||||||
purposes, the service **should** use the imperative mood. | ||||||
|
||||||
### Adjectives | ||||||
|
||||||
For consistency, field names that contain both a noun and an adjective | ||||||
**should** place the adjective _before_ the noun. For example: | ||||||
|
||||||
- `collected_items` (**not** `items_collected`) | ||||||
- `imported_objects` (**not** `objects_imported`) | ||||||
|
||||||
### Booleans | ||||||
lukesneeringer marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
||||||
Boolean fields **should** omit the prefix "is". For example: | ||||||
|
||||||
- `disabled` (**not** `is_disabled`) | ||||||
- `required` (**not** `is_required`) | ||||||
|
||||||
**Note:** Field names that would otherwise be [reserved words](#reserved-words) | ||||||
are an exception to this rule. For example, `is_new` (**not** `new`). | ||||||
|
||||||
### String vs. bytes | ||||||
lukesneeringer marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
||||||
When there is a need to send binary contents over the wire, the contents | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Nit: Capitalize |
||||||
**should** be base64-encoded and sent in a `string` field. Services **must** | ||||||
accept base64 encoding using the normal base64 alphabet, and **may** also | ||||||
accept URL-safe base64. | ||||||
|
||||||
**Note:** In IDLs that support `bytes` fields (such as protocol buffers), | ||||||
prefer the IDL's `bytes` implementation over asking the user to base64 encode | ||||||
and decode manually. | ||||||
|
||||||
### URIs | ||||||
|
||||||
Field names representing URLs or URIs **should** use `url` for fully-qualified | ||||||
URLs, and URIs for URI segment. Field names **may** use a prefix in front of | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Did you mean
Suggested change
|
||||||
`url` or `uri` as appropriate. | ||||||
|
||||||
### Reserved words | ||||||
|
||||||
Field names **should** avoid using names that are likely to conflict with | ||||||
keywords in common programming languages, such as `new`, `class`, `function`, | ||||||
`import`, etc. Reserved keywords can cause hardship for developers using the | ||||||
API in that language. | ||||||
|
||||||
### Conflicts | ||||||
|
||||||
Structs **should not** include a field with the same name as the enclosing | ||||||
structs (ignoring case transformations). This tends to cause conflicts when | ||||||
generating code. | ||||||
|
||||||
### Display names | ||||||
|
||||||
Many resources have a human-readable name, often used for display in UI. This | ||||||
field **must** generally be called `display_name`, and **must not** have a | ||||||
uniqueness requirement. | ||||||
|
||||||
If an entity has an official, formal name (such as a company name or the title | ||||||
of a book), an API **may** use `title` as the field name instead. The `title` | ||||||
field **should not** have a uniqueness requirement. | ||||||
|
||||||
## Further reading | ||||||
|
||||||
- For naming resource fields, see AIP-122. | ||||||
- For naming fields representing quantities, see AIP-141. | ||||||
- For naming fields representing time, see AIP-142. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
--- | ||
id: 140 | ||
state: approved | ||
created: 2019-07-22 | ||
placement: | ||
category: fields | ||
order: 0 |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.
@mkistler: One thing we do is check type / name consistency.