Standard fields
Number	148
Permalink	aip.kolla.dev/148
State	Approved
Created	2020-10-06
Updated	2020-10-06

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.