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 31syntax = "proto3"; 32 33package google.protobuf; 34 35option csharp_namespace = "Google.Protobuf.WellKnownTypes"; 36option java_package = "com.google.protobuf"; 37option java_outer_classname = "FieldMaskProto"; 38option java_multiple_files = true; 39option objc_class_prefix = "GPB"; 40option go_package = "google.golang.org/protobuf/types/known/fieldmaskpb"; 41option 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 unmappable. 242message FieldMask { 243 // The set of field mask paths. 244 repeated string paths = 1; 245} 246