• File Bug
• View source
• Edit this page

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 usedconsistently to communicate that concept.

Guidance

Standard fieldsshould be used to describe their corresponding concept, andshould not be used for any other purpose.

Resource names and IDs

name

Every resourcemust have astring name field, used for the resource name(AIP-122), whichshould be the first field in the resource.

Note: The_name suffixshould not be used to describe other types ofnames unless otherwise covered in this AIP.

parent

Thestring parent field refers to the resource name of the parent of acollection, andshould be used in mostList (AIP-132) andCreate(AIP-133) requests.

Other names

display_name

Thestring display_name fieldmust be a mutable, user-settable fieldwhere the user can provide a human-readable name to be used in user interfaces.Declarative-friendly resourcesshould include this field.

Display namesshould not have uniqueness requirements, andshould belimited to <= 63 characters.

title

Thestring title fieldshould be the official name of an entity, such asa company's name. This is a more formal variant ofstring display_name.

given_name

Thestring given_name fieldmust refer to a human or animal's given name.Resourcesmust not usefirst_name for this concept, because the givenname is not placed first in many cultures.

family_name

Thestring family_name fieldmust refer to a human or animal's familyname. Resourcesmust not uselast_name for this concept, because thefamily name is not placed last in many cultures.

Timestamps

create_time

The output onlygoogle.protobuf.Timestamp create_time fieldmustrepresent the timestamp when the resource was created. Thismay be eitherthe time creation was initiated or the time it was completed.Declarative-friendly resourcesshould include this field.

update_time

The output onlygoogle.protobuf.Timestamp update_time fieldmustrepresent the timestamp when the resource was most recently updated. Any changeto the resource made by usersmust refresh this value; changes to aresource made internally by the servicemay refresh this value.Declarative-friendly resourcesshould include this field.

delete_time

The output onlygoogle.protobuf.Timestamp delete_time fieldmust representthe timestamp that a resource was soft deleted. Thismay correspond to eitherthe time when the user requested deletion, or when the service successfullysoft deleted the resource. If a resource is not soft deleted, thedelete_timefieldmust be empty.

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

expire_time

Thegoogle.protobuf.Timestamp expire_time fieldshould represent the timethat a given resource or resource attribute is no longer useful or valid (e.g. arotating security key). Itmay be used for similar forms of expiration asdescribed inAIP-214.

Servicesmay provide anexpire_time value that is inexact, but theresourcemust not expire before that time.

purge_time

Thegoogle.protobuf.Timestamp purge_time fieldshould represent the timewhen a soft deleted resource will be purged from the system (seeAIP-164).Itmay be used for similar forms of expiration as described inAIP-214.Resources that support soft deleteshould include this field.

Servicesmay provide apurge_time value that is inexact, but the resourcemust not be purged from the system before that time.

Annotations

To store small amounts of arbitrary data, amap<string, string> annotationsfieldmay be added.

Theannotations fieldmust use theKubernetes limits to maintain wirecompatibility, andshould require dot-namespaced annotation keys to preventtools 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 beused by server-side policies, such as IAM conditions. Annotations exist toallow client tools to store their own state information without requiring adatabase.

Well known string fields

IP address

A field that represents an IP addressmust comply with the following:

• use typestring
• use the nameip_address or end with the suffix_ip_address e.g.resolved_ip_address
• specify the IP address version format via one of the supported formatsIPV4,IPV6, or if it can be either,IPV4_OR_IPV6 (seeAIP-202)

uid

The output onlystring uid field refers to a system-assigned uniqueidentifier for a resource. When provided, this fieldmust be aUUID4andmust specify this format via theUUID4 format extension (seeAIP-202).Declarative-friendly resourcesshould include thisfield.

Further reading

• For standardized codes, seeAIP-143.
• For theetag field, seeAIP-154.
• For therequest_id field, seeAIP-155.
• For thefilter field, seeAIP-160.
• For fields related to resource revisions, seeAIP-162.
• For thevalidate_only field, seeAIP-163.
• For fields related to soft delete and undelete, seeAIP-164.

Rationale

Well known string fields

Some fields represent very well defined concepts or artifacts that sometimesalso have strict governance of their semantics. For such fields, presenting anequally standardized API surface is important. This enables development ofimproved API consumer tools and documentation, as well as a more unified userexperience across the platform.

History

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

Changelog

• 2023-10-05: Introduce well known string fields with IP Address anduid.
• 2023-08-14: Introduce the termannotations fromAIP-128.
• 2023-07-13: Introduce the termpurge_time.
• 2021-04-06: Require output only field behavior foruid anddelete_time fields.