Two AIPs about FieldMask AIPs seem sensible in guidance but confusingly worded when directly contrasted

[esrauchg]

https://google.aip.dev/134 says:

The field must be optional, and the service must treat an omitted field mask as an implied field mask equivalent to all fields that are populated (have a non-empty value).
Update masks must support a special value `*`, meaning full replacement (the equivalent of PUT).

https://google.aip.dev/157 says:

An explicit value of `"*"` should be supported, and must return all fields.
If the field mask parameter is omitted, it must default to `"*"`, unless otherwise documented.

1. 157 wording seems a little weird in isolation, since it first says SHOULD accept explicit "*" (meaning it might not) but then if its omitted it MUST default to "*".

I think the only sensible interpretation here is 'omitted fieldmask must return all fields, even if explicit value of "*" is not accepted, unless otherwise documented", but it might be clearer to write it that way if thats the correct intepretation.

2. I think a real distinction exists that 134 is about UPDATE and 157 is about GET/LIST. On UPDATE there's two possible 'all' semantics (replace only what I'm giving you, or clobber the complete entity that is there which may have fields set that are unset in my new entry) and so the "*" vs absent is making that distinction between those two. Versus on GET theres really only one possible 'all' semantic (get everything that exists there).

The MUST (134) vs SHOULD (157) is a bit curious, but maybe justifiable that on GET there's only one semantic which must be reachable by an omitted fieldmask anyway?

I think the wording on 157 being that way is a little bit confusing though; if you read 157 in isolation you reasonably might think that its saying saying "*" and absent should be understood as the same thing in all cases, whereas 134 is explicitly declaring them as 2 different things.

That might just already go away if you adjusted 157's wording based on the prior feedback point above though where saying "omitted fieldmask must return all fields", but it might be worth an inline clarification that 157 fieldmask discussion is about GET/LIST/etc and call out 134 exists for the UPDATE case, unset and "*" end up both meaning "all data you have" on GET but end up having two different semantics on UPDATE.