Auth and Field Masks

Welcome to the seventh edition of the AIP newsletter, which is designed to keep you up to date about the AIP program, and particular proposals making their way through the system.

We have three new AIPs this month. As always, the AIP newsletter kicks off what is effectively a "public comment" period: the AIP editors are happy with this proposal, but we want to ensure that you are too. Assuming feedback is sufficiently positive, we intend to formally approve these proposals on Friday, March 26, 2021.

AIPs under review

AIP-149: Unset field values

In many messages, many fields are optional: the user is not required to provide them, or for output fields, the service might not populate the field.

Unset field values refer to primitive fields where the service makes a meaningful distinction between an empty value (such as 0 or false) and not setting the value at all. While this is generally discouraged if an alternative design is feasible, there are certainly occasions where this is the best approach.

Summary: AIP-149 provides guidance around use of the optional keyword for primitives.

We are aiming to approve AIP-149 on March 26. If you have feedback, please leave a comment.

AIP-161: Field masks

Often, when updating resources, it is desirable to specify exactly which fields are being updated, so that the service can ignore the rest, even if the user sends new values.

Field masks are the way that users are able to specify exactly which fields to read or update. They are necessary to ensure that adding fields to existing messages remains backwards-compatible.

While we have had an internal specification for field masks for some time, this AIP publicizes the specification.

Summary: AIP-161 provides a public specification for field masks.

We are aiming to approve AIP-161 on March 26. If you have feedback, please leave a comment.

AIP-211: Authorization checks

The majority of operations, whether reads or writes, require authorization: permission to do the thing the user is asking to do. Additionally, it is important to be careful how much information is provided to unauthorized users, since leaking information can be a security concern.

Authorization checks discusses when in the logical process of a request the authorization check ought to occur, and what error to send when an auth check fails.

In particular, if an authorization check fails, regardless of whether the resource exists, the service consistently returns PERMISSION_DENIED with an error message that also indicates that the resource might not exist.

Summary: AIP-211 provides guidance about authorization checks: when to perform them, and what error to send.

We are aiming to approve AIP-211 on March 26. If you have feedback, please leave a comment.

Additional approvals

We also intend to approve the AIPs that were placed under review in the October 2020 newsletter. This includes AIP-128 (#708), AIP-148 (#710), and AIP-164 (#709). If you have feedback, please leave a comment in the referenced pull requests.

Recent updates

In addition to the new AIPs under review, we have added the following guidance to existing AIPs:

  • AIP-144: Expand Add and Remove guidance. (#648)
  • AIP-154: Etag failures should use ABORTED. (#705)
  • AIP-162: Forbid deleting the only remaining revision. (#692)
  • AIP-162: Restrict revision tags to lower-case. (#707)
  • AIP-165: Make implicit recommendations more explicit. (#662)
  • AIP-203: Add UNORDERED_LIST to field behaviors. (#671)