1// Copyright 2020 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;
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