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