github.com/polarismesh/polaris@v1.17.8/common/api/protoc/include/google/protobuf/field_mask.proto (about) 1 // Protocol Buffers - Google's data interchange format 2 // Copyright 2008 Google Inc. All rights reserved. 3 // https://developers.google.com/protocol-buffers/ 4 // 5 // Redistribution and use in source and binary forms, with or without 6 // modification, are permitted provided that the following conditions are 7 // met: 8 // 9 // * Redistributions of source code must retain the above copyright 10 // notice, this list of conditions and the following disclaimer. 11 // * Redistributions in binary form must reproduce the above 12 // copyright notice, this list of conditions and the following disclaimer 13 // in the documentation and/or other materials provided with the 14 // distribution. 15 // * Neither the name of Google Inc. nor the names of its 16 // contributors may be used to endorse or promote products derived from 17 // this software without specific prior written permission. 18 // 19 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 24 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 25 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 31 syntax = "proto3"; 32 33 package google.protobuf; 34 35 option csharp_namespace = "Google.Protobuf.WellKnownTypes"; 36 option java_package = "com.google.protobuf"; 37 option java_outer_classname = "FieldMaskProto"; 38 option java_multiple_files = true; 39 option objc_class_prefix = "GPB"; 40 option go_package = "google.golang.org/genproto/protobuf/field_mask;field_mask"; 41 option cc_enable_arenas = true; 42 43 // `FieldMask` represents a set of symbolic field paths, for example: 44 // 45 // paths: "f.a" 46 // paths: "f.b.d" 47 // 48 // Here `f` represents a field in some root message, `a` and `b` 49 // fields in the message found in `f`, and `d` a field found in the 50 // message in `f.b`. 51 // 52 // Field masks are used to specify a subset of fields that should be 53 // returned by a get operation or modified by an update operation. 54 // Field masks also have a custom JSON encoding (see below). 55 // 56 // # Field Masks in Projections 57 // 58 // When used in the context of a projection, a response message or 59 // sub-message is filtered by the API to only contain those fields as 60 // specified in the mask. For example, if the mask in the previous 61 // example is applied to a response message as follows: 62 // 63 // f { 64 // a : 22 65 // b { 66 // d : 1 67 // x : 2 68 // } 69 // y : 13 70 // } 71 // z: 8 72 // 73 // The result will not contain specific values for fields x,y and z 74 // (their value will be set to the default, and omitted in proto text 75 // output): 76 // 77 // 78 // f { 79 // a : 22 80 // b { 81 // d : 1 82 // } 83 // } 84 // 85 // A repeated field is not allowed except at the last position of a 86 // paths string. 87 // 88 // If a FieldMask object is not present in a get operation, the 89 // operation applies to all fields (as if a FieldMask of all fields 90 // had been specified). 91 // 92 // Note that a field mask does not necessarily apply to the 93 // top-level response message. In case of a REST get operation, the 94 // field mask applies directly to the response, but in case of a REST 95 // list operation, the mask instead applies to each individual message 96 // in the returned resource list. In case of a REST custom method, 97 // other definitions may be used. Where the mask applies will be 98 // clearly documented together with its declaration in the API. In 99 // any case, the effect on the returned resource/resources is required 100 // behavior for APIs. 101 // 102 // # Field Masks in Update Operations 103 // 104 // A field mask in update operations specifies which fields of the 105 // targeted resource are going to be updated. The API is required 106 // to only change the values of the fields as specified in the mask 107 // and leave the others untouched. If a resource is passed in to 108 // describe the updated values, the API ignores the values of all 109 // fields not covered by the mask. 110 // 111 // If a repeated field is specified for an update operation, new values will 112 // be appended to the existing repeated field in the target resource. Note that 113 // a repeated field is only allowed in the last position of a `paths` string. 114 // 115 // If a sub-message is specified in the last position of the field mask for an 116 // update operation, then new value will be merged into the existing sub-message 117 // in the target resource. 118 // 119 // For example, given the target message: 120 // 121 // f { 122 // b { 123 // d: 1 124 // x: 2 125 // } 126 // c: [1] 127 // } 128 // 129 // And an update message: 130 // 131 // f { 132 // b { 133 // d: 10 134 // } 135 // c: [2] 136 // } 137 // 138 // then if the field mask is: 139 // 140 // paths: ["f.b", "f.c"] 141 // 142 // then the result will be: 143 // 144 // f { 145 // b { 146 // d: 10 147 // x: 2 148 // } 149 // c: [1, 2] 150 // } 151 // 152 // An implementation may provide options to override this default behavior for 153 // repeated and message fields. 154 // 155 // In order to reset a field's value to the default, the field must 156 // be in the mask and set to the default value in the provided resource. 157 // Hence, in order to reset all fields of a resource, provide a default 158 // instance of the resource and set all fields in the mask, or do 159 // not provide a mask as described below. 160 // 161 // If a field mask is not present on update, the operation applies to 162 // all fields (as if a field mask of all fields has been specified). 163 // Note that in the presence of schema evolution, this may mean that 164 // fields the client does not know and has therefore not filled into 165 // the request will be reset to their default. If this is unwanted 166 // behavior, a specific service may require a client to always specify 167 // a field mask, producing an error if not. 168 // 169 // As with get operations, the location of the resource which 170 // describes the updated values in the request message depends on the 171 // operation kind. In any case, the effect of the field mask is 172 // required to be honored by the API. 173 // 174 // ## Considerations for HTTP REST 175 // 176 // The HTTP kind of an update operation which uses a field mask must 177 // be set to PATCH instead of PUT in order to satisfy HTTP semantics 178 // (PUT must only be used for full updates). 179 // 180 // # JSON Encoding of Field Masks 181 // 182 // In JSON, a field mask is encoded as a single string where paths are 183 // separated by a comma. Fields name in each path are converted 184 // to/from lower-camel naming conventions. 185 // 186 // As an example, consider the following message declarations: 187 // 188 // message Profile { 189 // User user = 1; 190 // Photo photo = 2; 191 // } 192 // message User { 193 // string display_name = 1; 194 // string address = 2; 195 // } 196 // 197 // In proto a field mask for `Profile` may look as such: 198 // 199 // mask { 200 // paths: "user.display_name" 201 // paths: "photo" 202 // } 203 // 204 // In JSON, the same mask is represented as below: 205 // 206 // { 207 // mask: "user.displayName,photo" 208 // } 209 // 210 // # Field Masks and Oneof Fields 211 // 212 // Field masks treat fields in oneofs just as regular fields. Consider the 213 // following message: 214 // 215 // message SampleMessage { 216 // oneof test_oneof { 217 // string name = 4; 218 // SubMessage sub_message = 9; 219 // } 220 // } 221 // 222 // The field mask can be: 223 // 224 // mask { 225 // paths: "name" 226 // } 227 // 228 // Or: 229 // 230 // mask { 231 // paths: "sub_message" 232 // } 233 // 234 // Note that oneof type names ("test_oneof" in this case) cannot be used in 235 // paths. 236 // 237 // ## Field Mask Verification 238 // 239 // The implementation of any API method which has a FieldMask type field in the 240 // request should verify the included field paths, and return an 241 // `INVALID_ARGUMENT` error if any path is duplicated or unmappable. 242 message FieldMask { 243 // The set of field mask paths. 244 repeated string paths = 1; 245 }