|
| 1 | +// Copyright 2018 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; |
| 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 | +} |
0 commit comments