Skip to content

Support required in create for google.api.field_behavior to distinguish field requirements in create and update requests #20410

Open
@woshizhicainiaoluguo

Description

What language does this apply to?
golang

If it's a proto syntax change, is it for proto2 or proto3?
proto3

If it's about generated code change, what programming language?
golang openapi.yaml

Describe the problem you are trying to solve.
In the current proto specification, AIP-203 defines several google.api.field_behavior options, including required, optional, and output_only. However, it lacks a required in create behavior definition.

According to AIP-133 and AIP-134, the same object (e.g., Book book) should be used for both create and update requests, with the update_mask specifying the fields to be updated in the update interface.

If a field such as book.name is declared as google.api.field_behavior = required the generated openapi.yaml will mark book.name with an asterisk (*) as a required field. While it is expected that book.name is mandatory in the create interface, it becomes problematic when the update interface does not allow modifications to this field but still marks it as required. This inconsistency causes confusion for users.

Describe the solution you'd like
It is suggested to add a required in create behavior to address this issue and better align with practical use cases.

Describe alternatives you've considered
None

Additional context
None

Proto Detail

syntax = "proto3";
package book;

import "google/protobuf/field_mask.proto";
import "google/api/annotations.proto";
import "google/api/field_behavior.proto";

service BookService {
  rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/test/books/{id}"
    body: "book"
  };
}

rpc UpdateBook(UpdateBookRequest) returns (Book) {
  option (google.api.http) = {
    patch: "/v1/test/books/{id}"
    body: "book"
  };
  option (google.api.method_signature) = "book,update_mask";
}
}

message CreateBookRequest {
  string id = 1 [(google.api.field_behavior) = REQUIRED];
  // The book to create.
  Book book = 2 [(google.api.field_behavior) = REQUIRED];
}

message UpdateBookRequest {
  string id = 1 [(google.api.field_behavior) = REQUIRED];
  Book book = 2 [(google.api.field_behavior) = REQUIRED];
  // The list of fields to update.
  google.protobuf.FieldMask update_mask = 3[(google.api.field_behavior) = REQUIRED];
}

message Book {
  string name = 1 [(google.api.field_behavior) = REQUIRED];
  string title = 2;
  string author = 3;
  int32 rating = 4;
}

Result

Image

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Assignees

No one assigned

    Labels

    untriagedauto added to all issues by default when created.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions