1// Copyright 2019 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// 15 16syntax = "proto3"; 17 18package google.api; 19 20import "google/protobuf/descriptor.proto"; 21 22option go_package = "google.golang.org/genproto/googleapis/api/annotations;annotations"; 23option java_multiple_files = true; 24option java_outer_classname = "FieldBehaviorProto"; 25option java_package = "com.google.api"; 26option objc_class_prefix = "GAPI"; 27 28extend google.protobuf.FieldOptions { 29 // A designation of a specific field behavior (required, output only, etc.) 30 // in protobuf messages. 31 // 32 // Examples: 33 // 34 // string name = 1 [(google.api.field_behavior) = REQUIRED]; 35 // State state = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; 36 // google.protobuf.Duration ttl = 1 37 // [(google.api.field_behavior) = INPUT_ONLY]; 38 // google.protobuf.Timestamp expire_time = 1 39 // [(google.api.field_behavior) = OUTPUT_ONLY, 40 // (google.api.field_behavior) = IMMUTABLE]; 41 repeated google.api.FieldBehavior field_behavior = 1052; 42} 43 44// An indicator of the behavior of a given field (for example, that a field 45// is required in requests, or given as output but ignored as input). 46// This **does not** change the behavior in protocol buffers itself; it only 47// denotes the behavior and may affect how API tooling handles the field. 48// 49// Note: This enum **may** receive new values in the future. 50enum FieldBehavior { 51 // Conventional default for enums. Do not use this. 52 FIELD_BEHAVIOR_UNSPECIFIED = 0; 53 54 // Specifically denotes a field as optional. 55 // While all fields in protocol buffers are optional, this may be specified 56 // for emphasis if appropriate. 57 OPTIONAL = 1; 58 59 // Denotes a field as required. 60 // This indicates that the field **must** be provided as part of the request, 61 // and failure to do so will cause an error (usually `INVALID_ARGUMENT`). 62 REQUIRED = 2; 63 64 // Denotes a field as output only. 65 // This indicates that the field is provided in responses, but including the 66 // field in a request does nothing (the server *must* ignore it and 67 // *must not* throw an error as a result of the field's presence). 68 OUTPUT_ONLY = 3; 69 70 // Denotes a field as input only. 71 // This indicates that the field is provided in requests, and the 72 // corresponding field is not included in output. 73 INPUT_ONLY = 4; 74 75 // Denotes a field as immutable. 76 // This indicates that the field may be set once in a request to create a 77 // resource, but may not be changed thereafter. 78 IMMUTABLE = 5; 79} 80