1+ // Copyright 2024 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+ syntax = "proto3" ;
16+
17+ package google.api ;
18+
19+ import "google/protobuf/descriptor.proto" ;
20+
21+ option go_package = "google.golang.org/genproto/googleapis/api/annotations;annotations" ;
22+ option java_multiple_files = true ;
23+ option java_outer_classname = "FieldBehaviorProto" ;
24+ option java_package = "com.google.api" ;
25+ option objc_class_prefix = "GAPI" ;
26+
27+ extend 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.
49+ enum 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+ }
0 commit comments