Added required order independence.

aip/client-libraries/4223.md

@@ -0,0 +1,44 @@
+---
+id: 4223
+state: approved
+created: 2022-05-13
+---
+
+# Client-side payload validation
+
+Client-side payload validation is the practice of inspecting the request payload
+for any misconfigurations (e.g. missing required fields, attempting to update an
+immutable field) prior to executing a network call with the payload. Typically,
+documentation communicates the expectations of the service with regards to each
+request field, including any requirements on presence or format. The
+`google.api.field_behavior` annotation defined in [AIP-203][] is the
+machine-readable format that services use to document behavior in relation to
+specific request fields.
+
+## Guidance
+
+Client libraries **must not** implement client-side payload validation based
+on the `google.api.field_behavior` annotation, except to prevent
+[local failures](4223.md#local-failures).
+
+The reason for this is that the `google.api.field_behavior` annotation is
+primarily a machine-readable form of _documentation_, and **not** a
+configuration for payload validation. The annotation conveys how the service
+_already_ handles the field, and alludes to a service's own payload validation
+or expectations.
+
+Admittedly, depending on services to implement payload validation means clients
+will sometimes make network calls that are bound to result in errors. Furthermore, users
+then depend on services to provide actionable errors, when the client could have
+provided a language-idiomatic, localized error. However, robust server-side
+payload validation means that _all types_ of client (first party, third party,
+`curl`, etc.) will benefit from the **same** validation, and that there is no
+lag between service and clients when the field behavior changes.
+
+### Local failures
+
+Client libraries **may** implement client-side payload validation based on the
+`google.api.field_behavior` annotation only to the extent that it prevents
+local failures, such as crashes within the client library code itself.
+
+[AIP-203]: ../general/0203.md

aip/general/0234.md

@@ -42,6 +42,8 @@ rpc BatchUpdateBooks(BatchUpdateBooksRequest) returns (BatchUpdateBooksResponse)
   succeed for all resources (no partial success).
   - If the operation covers multiple locations and at least one location is
     down, the operation **must** fail.
+- The operation **must** execute independent updates based on a point-in-time
+  snapshot. It is thus independent of the order of requests.
 
 ### Request message
 
@@ -111,6 +113,7 @@ message BatchUpdateBooksResponse {
 
 ## Changelog
 
+- **2022-05-13**: Added required order independence.
 - **2020-09-16**: Suggested annotating `parent` and `requests` fields.
 - **2020-08-27**: Removed parent recommendations for top-level resources.
 - **2019-09-11**: Fixed the wording about which child field the `parent` field