AIP-4223

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.

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.