codekingpro/portable-devtools

1// Copyright 2023 Google LLC2//3// Licensed under the Apache License, Version 2.0 (the "License");4// you may not use this file except in compliance with the License.5// You may obtain a copy of the License at6//7//     http://www.apache.org/licenses/LICENSE-2.08//9// Unless required by applicable law or agreed to in writing, software10// distributed under the License is distributed on an "AS IS" BASIS,11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.12// See the License for the specific language governing permissions and13// limitations under the License.14 15syntax = "proto3";16 17package google.api;18 19import "google/protobuf/descriptor.proto";20 21option go_package = "google.golang.org/genproto/googleapis/api/annotations;annotations";22option java_multiple_files = true;23option java_outer_classname = "FieldBehaviorProto";24option java_package = "com.google.api";25option objc_class_prefix = "GAPI";26 27extend google.protobuf.FieldOptions {28  // A designation of a specific field behavior (required, output only, etc.)29  // in protobuf messages.30  //31  // Examples:32  //33  //   string name = 1 [(google.api.field_behavior) = REQUIRED];34  //   State state = 1 [(google.api.field_behavior) = OUTPUT_ONLY];35  //   google.protobuf.Duration ttl = 136  //     [(google.api.field_behavior) = INPUT_ONLY];37  //   google.protobuf.Timestamp expire_time = 138  //     [(google.api.field_behavior) = OUTPUT_ONLY,39  //      (google.api.field_behavior) = IMMUTABLE];40  repeated google.api.FieldBehavior field_behavior = 1052 [packed = false];41}42 43// An indicator of the behavior of a given field (for example, that a field44// is required in requests, or given as output but ignored as input).45// This **does not** change the behavior in protocol buffers itself; it only46// denotes the behavior and may affect how API tooling handles the field.47//48// Note: This enum **may** receive new values in the future.49enum FieldBehavior {50  // Conventional default for enums. Do not use this.51  FIELD_BEHAVIOR_UNSPECIFIED = 0;52 53  // Specifically denotes a field as optional.54  // While all fields in protocol buffers are optional, this may be specified55  // for emphasis if appropriate.56  OPTIONAL = 1;57 58  // Denotes a field as required.59  // This indicates that the field **must** be provided as part of the request,60  // and failure to do so will cause an error (usually `INVALID_ARGUMENT`).61  REQUIRED = 2;62 63  // Denotes a field as output only.64  // This indicates that the field is provided in responses, but including the65  // field in a request does nothing (the server *must* ignore it and66  // *must not* throw an error as a result of the field's presence).67  OUTPUT_ONLY = 3;68 69  // Denotes a field as input only.70  // This indicates that the field is provided in requests, and the71  // corresponding field is not included in output.72  INPUT_ONLY = 4;73 74  // Denotes a field as immutable.75  // This indicates that the field may be set once in a request to create a76  // resource, but may not be changed thereafter.77  IMMUTABLE = 5;78 79  // Denotes that a (repeated) field is an unordered list.80  // This indicates that the service may provide the elements of the list81  // in any arbitrary  order, rather than the order the user originally82  // provided. Additionally, the list's order may or may not be stable.83  UNORDERED_LIST = 6;84 85  // Denotes that this field returns a non-empty default value if not set.86  // This indicates that if the user provides the empty value in a request,87  // a non-empty value will be returned. The user will not be aware of what88  // non-empty value to expect.89  NON_EMPTY_DEFAULT = 7;90 91  // Denotes that the field in a resource (a message annotated with92  // google.api.resource) is used in the resource name to uniquely identify the93  // resource. For AIP-compliant APIs, this should only be applied to the94  // `name` field on the resource.95  //96  // This behavior should not be applied to references to other resources within97  // the message.98  //99  // The identifier field of resources often have different field behavior100  // depending on the request it is embedded in (e.g. for Create methods name101  // is optional and unused, while for Update methods it is required). Instead102  // of method-specific annotations, only `IDENTIFIER` is required.103  IDENTIFIER = 8;104}105