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 shouldbe used to describe their corresponding concept, and should notbe used for any other purpose.
Resource names and IDs
name
Every resource musthave a string name
field, used for the resource name
( AIP-122
), which shouldbe the first field in the resource.
Note:The _name
suffix should notbe 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 shouldbe used in most List
( AIP-132
) and Create
( AIP-133
) requests.
Other names
display_name
The string display_name
field mustbe a mutable, user-settable field
where the user can provide a human-readable name to be used in user interfaces. Declarative-friendly resources
shouldinclude this field.
Display names should nothave uniqueness requirements, and shouldbe limited to <= 63 characters.
title
The string title
field shouldbe 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 mustrefer to a human or animal's given name.
Resources must notuse first_name
for this concept, because the given
name is not placed first in many cultures.
family_name
The string family_name
field mustrefer to a human or animal's family
name. Resources must notuse 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 mustrepresent the timestamp when the resource was created. This maybe either
the time creation was initiated or the time it was completed. Declarative-friendly resources
shouldinclude this field.
update_time
The output only google.protobuf.Timestamp update_time
field mustrepresent the timestamp when the resource was most recently updated. Any change
to the resource made by users mustrefresh this value; changes to a
resource made internally by the service mayrefresh this value. Declarative-friendly resources
shouldinclude this field.
delete_time
The output only google.protobuf.Timestamp delete_time
field mustrepresent
the timestamp that a resource was soft deleted. This maycorrespond 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 mustbe empty.
Resources that support soft delete ( AIP-164 ) shouldprovide this field.
expire_time
The google.protobuf.Timestamp expire_time
field shouldrepresent the time
that a given resource or resource attribute is no longer useful or valid (e.g. a
rotating security key). It maybe used for similar forms of expiration as
described in AIP-214
.
Services mayprovide an expire_time
value that is inexact, but the
resource must notexpire before that time.
purge_time
The google.protobuf.Timestamp purge_time
field shouldrepresent the time
when a soft deleted resource will be purged from the system (see AIP-164
).
It maybe used for similar forms of expiration as described in AIP-214
.
Resources that support soft delete shouldinclude this field.
Services mayprovide a purge_time
value that is inexact, but the resource must notbe purged from the system before that time.
Annotations
To store small amounts of arbitrary data, a map<string, string> annotations
field maybe added.
The annotations
field mustuse the Kubernetes limits
to maintain wire
compatibility, and shouldrequire 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 mustcomply with the following:
- use type
string - use the name
ip_addressor end with the suffix_ip_addresse.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 mustbe a UUID4
and mustspecify this format via the UUID4
format extension (see AIP-202
). Declarative-friendly resources
shouldinclude this
field.
Further reading
- For standardized codes, see AIP-143 .
- For the
etagfield, see AIP-154 . - For the
request_idfield, see AIP-155 . - For the
filterfield, see AIP-160 . - For fields related to resource revisions, see AIP-162 .
- For the
validate_onlyfield, 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
annotationsfrom AIP-128 . - 2023-07-13: Introduce the term
purge_time. - 2021-04-06: Require output only field behavior for
uidanddelete_timefields.
