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.
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
proxy_settings field might be as helpful as
shared_proxy_settings if there is no unshared variant.
Field definitions in protobuf files must use
These names are mapped to an appropriate naming convention in JSON and in
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, fields must not contain leading, trailing, or adjacent underscores.
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.
Repeated fields must use the proper plural form, such as
authors. On the other hand, non-repeated fields should use the singular
form such as
author. This implies that resource names should
use the singular form as well, since the field name should follow the resource
name (e.g., use
repeated Book books, not
Books books = 1).
Field names should not include prepositions (such as "with", "for", "at", "by", etc). For example:
It is easier for field names to match more often when following this
convention. 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
likely indicates that the book resource may be improperly structured and worth
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").
For uniformity, field names that contain both a noun and an adjective should place the adjective before the noun. For example:
Field names must not be named to reflect an intent or action. They must not be verbs. Rather, because the field defines the desired value for mutations, e.g. Create and Update, and the current value for reads, e.g. Get and List, the name must be a noun. It defines what is so, not what to do.
In contrast, method names, whether standard or custom, change facets of resources and are named as verbs.
Boolean fields should omit the prefix "is". For example:
Note: Field names that would otherwise be reserved words
are an exception to this rule. For example,
String vs. bytes
bytes, the contents of the field are base64-encoded when using
JSON on the wire. Services should use
bytes when there is a need to send
binary contents over the wire, and should not ask the user to manually
base64-encode a field into a
Field names representing URLs or URIs should always use
uri rather than
url. This is because while all URLs are URIs, not all URIs are URLs. Field
names may use a prefix in front of
uri as appropriate.
Field names should avoid using names that are likely to conflict with
keywords in common programming languages, such as
import, etc. Reserved keywords can cause hardship for developers using the
API in that language.
Messages should not include a field with the same name as the enclosing message (ignoring case transformations). This causes conflicts when generating code in some languages.
Many resources have a human-readable name, often used for display in UI. This
field should be called
display_name, and should not have a uniqueness
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
field should not have a uniqueness requirement.
- For naming resource fields, see AIP-122.
- For naming fields representing quantities, see AIP-141.
- For naming fields representing time, see AIP-142.
- 2023-04-25: Field names must not be expressed as verbs.
- 2021-07-12: Normalized display name guidance to "should".
- 2021-04-07: Added base64 and bytes guidance.
- 2021-03-05: Added prohibition on leading, trailing, or adjacent underscores.
- 2020-06-10: Added prohibition on starting any word with a number.
- 2020-05-29: Added guidance around URIs.
- 2020-03-24: Added guidance around conflicting field and message names.
- 2020-01-30: Added guidance around