AIP-148

Standard fields

Certain concepts are common throughout any corpus of APIs. In these situations, it is useful to have a standard field name and behavior that is used consistently to communicate that concept.

Guidance

Standard fields should be used to describe their corresponding concept, and should not be used for any other purpose.

Resource names and IDs

name

Every resource must have a string name field, used for the resource name (AIP-122), which should be the first field in the resource.

Note: The _name suffix should not be used to describe other types of names unless otherwise covered in this AIP.

parent

The string parent field refers to the resource name of the parent of a collection, and should be used in most List (AIP-132) and Create (AIP-133) requests.

Other names

display_name

The string display_name field must be a mutable, user-settable field where the user can provide a human-readable name to be used in user interfaces. Declarative-friendly resources should include this field.

Display names should not have uniqueness requirements, and should be limited to <= 63 characters.

title

The string title field should be the official name of an entity, such as a company's name. This is a more formal variant of string display_name.

given_name

The string given_name field must refer to a human or animal's given name. Resources must not use first_name for this concept, because the given name is not placed first in many cultures.

family_name

The string family_name field must refer to a human or animal's family name. Resources must not use last_name for this concept, because the family name is not placed last in many cultures.

Timestamps

create_time

The output only google.protobuf.Timestamp create_time field must represent the timestamp when the resource was created. This may be either the time creation was initiated or the time it was completed. Declarative-friendly resources should include this field.

update_time

The output only google.protobuf.Timestamp update_time field must represent the timestamp when the resource was most recently updated. Any change to the resource made by users must refresh this value; changes to a resource made internally by the service may refresh this value. Declarative-friendly resources should include this field.

delete_time

The output only google.protobuf.Timestamp delete_time field must represent the timestamp that a resource was soft deleted. This may correspond to either the time when the user requested deletion, or when the service successfully soft deleted the resource. If a resource is not soft deleted, the delete_time field must be empty.

Resources that support soft delete (AIP-164) should provide this field.

expire_time

The google.protobuf.Timestamp expire_time field should represent the time that a given resource or resource attribute is no longer useful or valid (e.g. a rotating security key). It may be used for similar forms of expiration as described in AIP-214.

Services may provide an expire_time value that is inexact, but the resource must not expire before that time.

purge_time

The google.protobuf.Timestamp purge_time field should represent the time when a soft deleted resource will be purged from the system (see AIP-164). It may be used for similar forms of expiration as described in AIP-214. Resources that support soft delete should include this field.

Services may provide a purge_time value that is inexact, but the resource must not be purged from the system before that time.

Annotations

To store small amounts of arbitrary data, a map<string, string> annotations field may be added.

The annotations field must use the Kubernetes limits to maintain wire compatibility, and should require dot-namespaced annotation keys to prevent tools from trampling over one another.

Examples of information that might be valuable to store in annotations include:

  • For CI/CD, an identifier of the pipeline run or version control identifier used to propagate.

Note: Annotations are distinct from various forms of labels. Labels can be used by server-side policies, such as IAM conditions. Annotations exist to allow client tools to store their own state information without requiring a database.

Well known string fields

IP address

A field that represents an IP address must comply with the following:

  • use type string
  • use the name ip_address or end with the suffix _ip_address e.g. resolved_ip_address
  • specify the IP address version format via one of the supported formats IPV4, IPV6, or if it can be either, IPV4_OR_IPV6 (see AIP-202)

uid

The output only string uid field refers to a system-assigned unique identifier for a resource. When provided, this field must be a UUID4 and must specify this format via the UUID4 format extension (see AIP-202). Declarative-friendly resources should include this field.

Further reading

  • For standardized codes, see AIP-143.
  • For the etag field, see AIP-154.
  • For the request_id field, see AIP-155.
  • For the filter field, see AIP-160.
  • For fields related to resource revisions, see AIP-162.
  • For the validate_only field, see AIP-163.
  • For fields related to soft delete and undelete, see AIP-164.

Rationale

Well known string fields

Some fields represent very well defined concepts or artifacts that sometimes also have strict governance of their semantics. For such fields, presenting an equally standardized API surface is important. This enables development of improved API consumer tools and documentation, as well as a more unified user experience across the platform.

History

Before 2023-07, purge_time for soft-deleted resources was also called expire_time. purge_time was introduced to reduce user confusion.

Changelog

  • 2023-10-05: Introduce well known string fields with IP Address and uid.
  • 2023-08-14: Introduce the term annotations from AIP-128.
  • 2023-07-13: Introduce the term purge_time.
  • 2021-04-06: Require output only field behavior for uid and delete_time fields.