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 java_generate_equals_and_hash = true; 41 42 // `FieldMask` represents a set of symbolic field paths, for example: 43 // 44 // paths: "f.a" 45 // paths: "f.b.d" 46 // 47 // Here `f` represents a field in some root message, `a` and `b` 48 // fields in the message found in `f`, and `d` a field found in the 49 // message in `f.b`. 50 // 51 // Field masks are used to specify a subset of fields that should be 52 // returned by a get operation or modified by an update operation. 53 // Field masks also have a custom JSON encoding (see below). 54 // 55 // # Field Masks in Projections 56 // 57 // When used in the context of a projection, a response message or 58 // sub-message is filtered by the API to only contain those fields as 59 // specified in the mask. For example, if the mask in the previous 60 // example is applied to a response message as follows: 61 // 62 // f { 63 // a : 22 64 // b { 65 // d : 1 66 // x : 2 67 // } 68 // y : 13 69 // } 70 // z: 8 71 // 72 // The result will not contain specific values for fields x,y and z 73 // (their value will be set to the default, and omitted in proto text 74 // output): 75 // 76 // 77 // f { 78 // a : 22 79 // b { 80 // d : 1 81 // } 82 // } 83 // 84 // A repeated field is not allowed except at the last position of a 85 // field mask. 86 // 87 // If a FieldMask object is not present in a get operation, the 88 // operation applies to all fields (as if a FieldMask of all fields 89 // had been specified). 90 // 91 // Note that a field mask does not necessarily apply to the 92 // top-level response message. In case of a REST get operation, the 93 // field mask applies directly to the response, but in case of a REST 94 // list operation, the mask instead applies to each individual message 95 // in the returned resource list. In case of a REST custom method, 96 // other definitions may be used. Where the mask applies will be 97 // clearly documented together with its declaration in the API. In 98 // any case, the effect on the returned resource/resources is required 99 // behavior for APIs. 100 // 101 // # Field Masks in Update Operations 102 // 103 // A field mask in update operations specifies which fields of the 104 // targeted resource are going to be updated. The API is required 105 // to only change the values of the fields as specified in the mask 106 // and leave the others untouched. If a resource is passed in to 107 // describe the updated values, the API ignores the values of all 108 // fields not covered by the mask. 109 // 110 // In order to reset a field's value to the default, the field must 111 // be in the mask and set to the default value in the provided resource. 112 // Hence, in order to reset all fields of a resource, provide a default 113 // instance of the resource and set all fields in the mask, or do 114 // not provide a mask as described below. 115 // 116 // If a field mask is not present on update, the operation applies to 117 // all fields (as if a field mask of all fields has been specified). 118 // Note that in the presence of schema evolution, this may mean that 119 // fields the client does not know and has therefore not filled into 120 // the request will be reset to their default. If this is unwanted 121 // behavior, a specific service may require a client to always specify 122 // a field mask, producing an error if not. 123 // 124 // As with get operations, the location of the resource which 125 // describes the updated values in the request message depends on the 126 // operation kind. In any case, the effect of the field mask is 127 // required to be honored by the API. 128 // 129 // ## Considerations for HTTP REST 130 // 131 // The HTTP kind of an update operation which uses a field mask must 132 // be set to PATCH instead of PUT in order to satisfy HTTP semantics 133 // (PUT must only be used for full updates). 134 // 135 // # JSON Encoding of Field Masks 136 // 137 // In JSON, a field mask is encoded as a single string where paths are 138 // separated by a comma. Fields name in each path are converted 139 // to/from lower-camel naming conventions. 140 // 141 // As an example, consider the following message declarations: 142 // 143 // message Profile { 144 // User user = 1; 145 // Photo photo = 2; 146 // } 147 // message User { 148 // string display_name = 1; 149 // string address = 2; 150 // } 151 // 152 // In proto a field mask for `Profile` may look as such: 153 // 154 // mask { 155 // paths: "user.display_name" 156 // paths: "photo" 157 // } 158 // 159 // In JSON, the same mask is represented as below: 160 // 161 // { 162 // mask: "user.displayName,photo" 163 // } 164 // 165 // # Field Masks and Oneof Fields 166 // 167 // Field masks treat fields in oneofs just as regular fields. Consider the 168 // following message: 169 // 170 // message SampleMessage { 171 // oneof test_oneof { 172 // string name = 4; 173 // SubMessage sub_message = 9; 174 // } 175 // } 176 // 177 // The field mask can be: 178 // 179 // mask { 180 // paths: "name" 181 // } 182 // 183 // Or: 184 // 185 // mask { 186 // paths: "sub_message" 187 // } 188 // 189 // Note that oneof type names ("test_oneof" in this case) cannot be used in 190 // paths. 191 message FieldMask { 192 // The set of field mask paths. 193 repeated string paths = 1; 194 } 195
