Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat(AIP-203): Disallow OUTPUT_ONLY fields with OPTIONAL/REQUIRED sub… #1276

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

feat(AIP-203): Disallow OUTPUT_ONLY fields with OPTIONAL/REQUIRED sub… #1276

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
49 changes: 48 additions & 1 deletion aip/general/0203.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ backwards-compatility. Nontheless, this annotation **must not** be omitted.
only, and does not itself add any validation. The purpose is to consistently
document this behavior for clients.

### field behavior of nested messages
### Field behavior of nested messages

`google.api.field_behavior` annotations on a nested message are independent of
the annotations of the parent.
Expand All @@ -62,6 +62,38 @@ message Slide {

In the case above, if a `title` is specified, the `text` field is required.

If a field containing a nested message is annotated as `OUTPUT_ONLY`,
all of the nested message fields **must** also be annotated as `OUTPUT_ONLY`.

For example, the following is incorrect as `text` is a required field:

```proto
message Title {
string text = 1 [(google.api.field_behavior) = REQUIRED];
}

message Slide {
// Incorrect. Title defines `text` as a required field.
Title title = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}
```

The following is correct, as `reverse` is a leaf field and does not
override behavior. If `Slide.title` is specified, `text` must be provided,
and `reverse` will be computed by the service and returned in responses:

```proto
message Title {
string text = 1 [(google.api.field_behavior) = REQUIRED];

string reverse = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
}

message Slide {
Title title = 1 [(google.api.field_behavior) = OPTIONAL];
}
```

## Vocabulary

### Identifier
Expand Down Expand Up @@ -264,6 +296,19 @@ RPC or a resource in a [Declarative client][]. See the
[Backwards compatibility](#backwards-compatibility) section for more detailed
compatibility guidance.

### Field behavior of nested messages

Nested messages allow avoiding code duplication, where the same type can be shared
by multiple messages. Given that field behavior annotations are also required for
nested messages, field behavior must also implicitly be shared. Annotating a field
with `OUTPUT_ONLY`, when the field is a sub-message declaring `REQUIRED` and/or
`OPTIONAL` fields, forces clients to treat this sub-message differently depending
on the context it is used in. Forcing services to consistently separate output
fields from user-defined fields avoids this problem. Additionally, there is little
value in annotating sub-fields of `OUTPUT_ONLY` fields as either `REQUIRED` or
`OPTIONAL`, since the consequences of breaking this contract by services still
have to be handled by clients.

## History

In 2023-05 field_behavior was made mandatory. Prior to this change, the
Expand All @@ -285,6 +330,8 @@ surpass the costs to clients and API users of not doing so.

## Changelog

- **2023-11-27**: Clarify that overriding behavior through nesting is only
- supported for REQUIRED and OPTIONAL.
- **2023-09-14**: Clarify that nested behavior and parent behavior are
independent.
- **2023-08-25**: Add guidance on `IDENTIFIER`.
Expand Down