feat(AIP-4223): add guidance on client-side validation (aip-dev#888)

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