diff --git a/aip/general/0126.md b/aip/general/0126.md index ee89943610..85f10cda29 100644 --- a/aip/general/0126.md +++ b/aip/general/0126.md @@ -54,7 +54,9 @@ message Book { followed by the suffix `_UNSPECIFIED`. - An exception to this rule is if there is a clearly useful zero value. In particular, if an enum needs to present an `UNKNOWN`, it is usually clearer - and more useful for it to be a zero value rather than having both. + and more useful for it to be a zero value rather than having both. The + `UNKNOWN` value **may** be prefixed by the enum name as is typical for + avoiding enum value name collisions. - Enums which will only be used in a single message **should** be nested within that message. In this case, the enum **should** be declared immediately before it is used. - The non-zero values of such a nested enum definition **should not** be prefixed by the name @@ -113,3 +115,7 @@ choice (although `google.protobuf.BoolValue` is also available). [aip-216]: ./0216.md [bcp-47]: https://en.wikipedia.org/wiki/IETF_language_tag [media types]: https://en.wikipedia.org/wiki/Media_type + +## Changelog + +- **2025-10-03**: Added prefixing guidance for `UNKNOWN` value exception. diff --git a/aip/general/0133.md b/aip/general/0133.md index fa5b0f6e9a..f834855840 100644 --- a/aip/general/0133.md +++ b/aip/general/0133.md @@ -43,7 +43,8 @@ rpc CreateBook(CreateBookRequest) returns (Book) { `CreateBookResponse`. - The response **should** include the fully-populated resource, and **must** include any fields that were provided unless they are input only (see - [AIP-203][]). + [AIP-203][]) or there is a reason to return a partial response (see + [AIP-157][]). - If the create RPC is [long-running](#long-running-create), the response message **must** be a `google.longrunning.Operation` which resolves to the resource itself. @@ -219,6 +220,7 @@ name and use it in references from other resources. ## Changelog +- **2025-10-03**: Allow use of partial responses via AIP-157. - **2023-10-20**: Clarify that {resource}_id is only required for management plane resources. - **2023-08-24**: Adding consistency requirement. - **2023-05-11**: Changing guidance around resource_id to a must. diff --git a/aip/general/0134.md b/aip/general/0134.md index e61bedc838..a42910c090 100644 --- a/aip/general/0134.md +++ b/aip/general/0134.md @@ -43,7 +43,8 @@ rpc UpdateBook(UpdateBookRequest) returns (Book) { `UpdateBookResponse`.) - The response **should** include the fully-populated resource, and **must** include any fields that were sent and included in the update mask unless - they are input only (see AIP-203). + they are input only (see AIP-203) or there is a reason to return a partial + response (see [AIP-157][]). - If the update RPC is [long-running](#long-running-update), the response message **must** be a `google.longrunning.Operation` which resolves to the resource itself. @@ -302,6 +303,7 @@ does not exist, the service **must** error with `NOT_FOUND` (HTTP 404) unless ## Changelog +- **2025-10-03**: Allow use of partial responses via AIP-157. - **2024-12-03**: Add caveats to usage of full replacement `update_mask`. - **2024-03-14**: Make `update_mask` optional field_behaviour guidance a **must**. - **2023-08-26**: Adding consistency requirement. diff --git a/aip/general/0157.md b/aip/general/0157.md index aa52f3ac51..15a65e845e 100644 --- a/aip/general/0157.md +++ b/aip/general/0157.md @@ -61,10 +61,15 @@ enum BookView { - The enum **should** at minimum have values named `BASIC` and `FULL` (although it **may** have values other than these). - The `UNSPECIFIED` value **must** be valid (not an error), and the API - **must** document what the unspecified value will do). + **must** document what the unspecified value will do. - For List RPCs, the effective default value **should** be `BASIC`. - - For Get RPCs, the effective default value **should** be either `BASIC` or - `FULL`. + - For the following RPC types, the effective default value **should** be + either `BASIC` or `FULL`: + - Get + - Create + - Update + - Soft Delete + - Custom Method - The enum **should** be defined at the top level of the proto file (as it is likely to be needed in multiple requests, e.g. both `Get` and `List`). See [AIP-126][] for more guidance on top-level enumerations. @@ -76,6 +81,11 @@ enum BookView { conflict. In this situation, the service **should** nest the view enum within the individual resource. + **Note:** Having a partial response be the default of standard methods can + degrade the effectiveness of declarative clients. Providing a mechanism to + request the full resource be populated in the response, like this View + pattern, is preferred if partial responses are deemed necessary. + ### Read masks as a request field **Warning:** Read mask as a single, explicit field on the request message is @@ -107,6 +117,8 @@ potential point of conflict for the client or service. ## Changelog +- **2025-10-03**: Added default view guidance for other RPC types, and + declarative client warning. - **2025-06-16**: Reinstate read mask guidance as historical/external reference. - **2023-05-09**: Fix top-level enum example and link to AIP-126. - **2022-03-14:** Updated guidance on default value and how to specify a read mask. diff --git a/aip/general/0160.md b/aip/general/0160.md index 5325645d64..3a6a7ee18f 100644 --- a/aip/general/0160.md +++ b/aip/general/0160.md @@ -183,6 +183,19 @@ There are two slight distinctions when parsing messages: implementations **may** choose to support automatic conversion between camel case and snake case. +For all aforementioned types, simply checking for the presence of a top-level +resource field is possible with the `*` value: + +| Example | Meaning | +| ---------- | ---------------------------------------- | +| `r:*` | True if `repeated` field `r` is present. | +| `p:*` | True if `map` field `p` is present. | +| `m:*` | True if `message` field `m` is present. | + +**Note:** For `map` and `repeated` fields, there is no semantic difference +between an unset field and "set with empty value" - they both resolve to "not +present". + ### Functions The filtering language supports a function call syntax in order to support @@ -231,5 +244,6 @@ Schematic validation refers, but is not limited to, the following: ## Changelog +- **2025-10-03**: Clarify top-level field has operator behavior. - **2025-01-07**: Clarify behavior for unset field in traversal operator chain. - **2024-12-11**: Move non-compliant filter guidance to Validation section. diff --git a/aip/general/0180.md b/aip/general/0180.md index 2bcad7f977..31af4a6ce7 100644 --- a/aip/general/0180.md +++ b/aip/general/0180.md @@ -64,6 +64,11 @@ However, keep the following guidelines in mind when doing this: resources. - Any field being populated by clients **must** have a default behavior matching the behavior before the field was introduced. + - This can be tricky to do in some cases. For example, adding pagination + after the fact where previously all items were returned (i.e. `page_size` + is infinite, which is not advised). If the default for the new `page_size` + field is _less_ than what was previously returned, older clients will + incorrectly assume all results were returned. - Any field previously populated by the server **must** continue to be populated, even if it introduces redundancy. - For enum values specifically, be aware that it is possible that user code @@ -113,6 +118,15 @@ Existing fields and messages **must not** have their type changed, even if the new type is wire-compatible, because type changes alter generated code in a breaking way. +### Changing string length + +APIs **should** avoid increasing the upper bound for the size or limit (if +accepted as input) of `string` fields. APIs **should** treat expected size upper +bound increases as incompatible changes (see [Changing resource names] +(#changing-resource-names) as an example). APIs **may** pad out values with +filler characters if reserving a consistent size is necessary, but this **must** +be documented if done. + ### Changing resource names A resource **must not** change its [name][aip-122]. @@ -146,6 +160,15 @@ code, as such changes will be seen as breaking by those users. whether a proposed change is likely to break users, and an expansive reading of this guidance could ostensibly prevent _any_ change (which is not the intent). +#### Changing value format or construction + +APIs **must not** change the expected format or algorithm used to construct the +value of an existing field - even if the field is `OUTPUT_ONLY` and populated by +the API service - within an API version. Doing so requires a new API version. + +For example, changing the format of a field `ip_address` conforming to IPv4 +format to instead contain IPv6 values is a breaking change. + #### Default values must not change Default values are the values set by servers for resources when they are not @@ -245,8 +268,27 @@ version. - For compatibility around field presence changes, see [AIP-149][]. - For compatibility around resource types, see [AIP-123][]. +## Rationale + +### Risk of string length changes + +End users may store resource properties, like the `name`, in a dedicated +database column with a limited length. If the service starts returning values +for the `name` that are twice the originally documented/observed length, this +may unexpectedly break the customer's database. Furthermore, string properties +that appear in URLs (including query parameters) are especially likely to have +client-side limits, making them more sensitive to length changes. + +### Risk of changing value format or construction + +Customers often depend on the format or algorithmic construction of a field for +client-side parsing, hashing, or database table construction. Changing it in +an existing field could break that client-side consumption. + ## Changelog +- **2025-10-21**: Added guidance for string length changes, changing formats, + and an example for carefully adding components. - **2024-08-07**: Added reference to resource type compatibility. - **2024-06-05**: Added reference to field presence compatibility. - **2023-07-26**: Added reference to field behavior compatibility.