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.

Important

Field names often appear in generated client surfaces. Ensure they are appropriately descriptive and of suitable length.

Case

Protocol Buffers

Field definitions in protobuf files must use lower_snake_case names. These names are mapped to an appropriate naming convention in JSON and in generated code.

OpenAPI 3.0

Field definitions in OAS schemas must use camelCase names.

Note

Examples throughout this AEP use snake_case. This should not be taken to mean that this guidance is protobuf-specific. Any guidance not in a protobuf tab applies to all APIs, with snake_case examples converted to camelCase for OAS APIs.

Each word in a field name 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.

Uniformity

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.

Arrays / Repeated fields

Arrays (in OAS) and repeated fields (in protobuf) must use the proper plural form, such as books or authors. On the other hand, singular fields must use the singular form such as book or author.

Prepositions

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)

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 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”).

Adjectives

For uniformity, 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)

Verbs

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.

• collected_items (not collect_items)
• disabled (not disable)

In contrast, method names, whether standard or custom, change facets of resources and are named as verbs.

Booleans

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 are an exception to this rule. For example, is_new (not new).

String vs. bytes

Protocol Buffers

When using bytes, the contents of the field are base64-encoded when using JSON on the wire. APIs 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 string field.

OpenAPI 3.0

Note: OAS guidance not yet written.

URIs

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.

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

Schemas should not include a field with the same name as the enclosing schema (ignoring case transformations). This causes conflicts when generating code in some languages.

Display names

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 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 paths.
• For naming fields representing quantities, see quantities.
• For naming fields representing time, see time-and-duration.