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

uid

The output only string uid field refers to a system-assigned, unique identifier for a resource. When provided, this field should be a UUID4. Declarative-friendly resources should include this field.

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 usually represent the time when a soft deleted resource will be purged from the system. It may be used for similar forms of expiration as described in AIP-214. Resources that support soft delete should include this field.

In some situations, it can be difficult to provide an exact expire_time value, because of implementation dependencies. Services may provide an expire_time value that is inexact, but the resource must not be expired from the system before that time.

Resources that support soft delete (AIP-164) should provide 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.

Changelog

  • 2021-04-06: Require output only field behavior for uid and delete_time fields.