aep.md.j2

# 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.

- Each word in a field name **must not** begin with a number, because it
  creates ambiguity when converting between snake case and camel case.
- Fields **must not** contain leading, trailing, or adjacent underscores.

### Case

JSON and protobuf fields **must** use `lower_snake_case` names. These names
**may** be mapped to a language-specific idiomatic naming convention in
generated code.

- Over-the-wire references to fields in other contexts (such as query
  parameters, path segments, and embedded CEL expressions) **must** not be
  transformed in any way, with the following exception:
  - If a field name is also be used as a header name, it **must** be
    transformed by substituting hyphens (`-`) for underscores (`_`), emitted in
    lowercase, and parsed case-insensitively.

#### Support for lowerCamelCase in clients

[ProtoJSON][proto-json] and [gRPC-Gateway][grpc-gateway] by default both
transform `lower_snake_case` protobuf field names into `lowerCamelCase` JSON
field names by default and an earlier draft of this AEP _required_ that JSON
field names be in `lowerCamelCase` (whether or not they are backed by
equivalent protobufs).

While APIs compliant with this AEP are required to use `lower_snake_case` JSON
field names, because of this history, tools for producing or consuming
AEP-compliant APIs **may** support `lowerCamelCase` JSON fields and first-party
tools (those included in the AEP project).

[proto-json]: https://protobuf.dev/programming-guides/json
[grpc-gateway]: https://grpc-ecosystem.github.io/grpc-gateway/

### 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](#reserved-words)
are an exception to this rule. For example, `is_new` (**not** `new`).

### String vs. bytes

{% tab proto %}

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.

{% tab oas %}

**Note:** OAS guidance not yet written.

{% endtabs %}

### URIs

Field names representing arbitrary URIs **should** use `uri`. In particular,
note that URLs are URIs but not all URIs are URLs.

Field names that can only represent a URL **should** use `url`.

Field names **may** use a prefix in front of `uri` or `url` as appropriate.

{% tab proto %}

```proto
message Book {
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];
  // A URL pointing to an image of the book.
  string image_url = 2;
  // A URI identifying the book.
  // This could be an ISBN or a URL.
  string uri = 3;
}
```

{% tab oas %}

```json
{
  "components": {
    "schemas": {
      "book": {
        "properties": {
          "image_url": {
            "type": "string",
            "format": "uri",
            "description": "A URL pointing to an image of the book."
          },
          "uri": {
            "type": "string",
            "format": "uri",
            "description": "A URI identifying the book. This could be an ISBN or a URL."
          }
        }
      }
    }
  }
}
```

{% endtabs %}

**Note:** APIs that have previously used `uri` for URL fields may continue to
do so to avoid unnecessary API changes and to preserve local consistency.

### 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](./paths).
- For naming fields representing quantities, see [quantities](./quantities).
- For naming fields representing time, see
  [time-and-duration](./time-and-duration).