1// Copyright 2023 Google LLC 2// 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 at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// 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 and 13// 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 = 1 36 // [(google.api.field_behavior) = INPUT_ONLY]; 37 // google.protobuf.Timestamp expire_time = 1 38 // [(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 field 44// is required in requests, or given as output but ignored as input). 45// This **does not** change the behavior in protocol buffers itself; it only 46// 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 specified 55 // 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 the 65 // field in a request does nothing (the server *must* ignore it and 66 // *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 the 71 // 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 a 76 // 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 list 81 // in any arbitrary order, rather than the order the user originally 82 // 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 what 88 // non-empty value to expect. 89 NON_EMPTY_DEFAULT = 7; 90 91 // Denotes that the field in a resource (a message annotated with 92 // google.api.resource) is used in the resource name to uniquely identify the 93 // resource. For AIP-compliant APIs, this should only be applied to the 94 // `name` field on the resource. 95 // 96 // This behavior should not be applied to references to other resources within 97 // the message. 98 // 99 // The identifier field of resources often have different field behavior 100 // depending on the request it is embedded in (e.g. for Create methods name 101 // is optional and unused, while for Update methods it is required). Instead 102 // of method-specific annotations, only `IDENTIFIER` is required. 103 IDENTIFIER = 8; 104} 105