search

aip-dev / google.aip.dev

API Improvement Proposals. https://aip.dev/
Other
1.08k stars 495 forks source link

[AIP-157] The value of the field mask parameter #1330

Open szk2s opened 7 months ago

szk2s commented 7 months ago

In AIP-157, it is stated:

The value of the field mask parameter must be a google.protobuf.FieldMask.

This wording might suggest that the value should be in the proto3 JSON representation of a google.protobuf.FieldMask, which I suspect not be the intended interpretation. Given that examples in the AIP include using this parameter as an HTTP query parameter, an HTTP header, and a gRPC metadata entry, it appears that the more prevalent practice is a comma-separated list of paths for specifying field masks. 

-H X-Goog-FieldMask: routes.distanceMeters,routes.duration

If my understanding is indeed correct, it might be clearer to revise the statement in AIP-157 to reflect this common usage, potentially rewording it as:

The value of the field mask parameter must be a comma-separated list of paths.

Thank you for considering this adjustment for clarity.