feat(AIP-148): add well known strings section (#1239)

Author: noahdietz

aip/general/0148.md

@@ -10,8 +10,8 @@ placement:
 # 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.
+it is useful to have a standard field name and behavior that is used
+consistently to communicate that concept.
 
 ## Guidance
 
@@ -34,15 +34,6 @@ 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.
-
-<!-- prettier-ignore -->
-[uuid4]: https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)
-
 ### Other names
 
 #### display_name
@@ -137,6 +128,25 @@ 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][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][aip-202]). [Declarative-friendly resources][] **should** include this
+field.
 
 ## Further reading
 
@@ -148,18 +158,31 @@ database.
 - 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.
 
 <!-- prettier-ignore -->
+[aip-202]: ./0202.md
 [declarative-friendly resources]: ./0128.md#resources
-[kubernetes limits]: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/#syntax-and-character-set
+[kubernetes limits]: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/#syntax-and-character-set
+[uuid4]: https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)