1 // Protocol Buffers - Google's data interchange format
2 // Copyright 2008 Google Inc. All rights reserved.
3 // https://developers.google.com/protocol-buffers/
5 // Redistribution and use in source and binary forms, with or without
6 // modification, are permitted provided that the following conditions are
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
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.
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.
33 package google.protobuf;
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;
43 // `FieldMask` represents a set of symbolic field paths, for example:
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
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).
56 // # Field Masks in Projections
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:
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
85 // A repeated field is not allowed except at the last position of a
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).
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.
102 // # Field Masks in Update Operations
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.
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.
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.
119 // For example, given the target message:
129 // And an update message:
138 // then if the field mask is:
140 // paths: ["f.b", "f.c"]
142 // then the result will be:
152 // An implementation may provide options to override this default behavior for
153 // repeated and message fields.
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.
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.
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.
174 // ## Considerations for HTTP REST
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).
180 // # JSON Encoding of Field Masks
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.
186 // As an example, consider the following message declarations:
193 // string display_name = 1;
194 // string address = 2;
197 // In proto a field mask for `Profile` may look as such:
200 // paths: "user.display_name"
204 // In JSON, the same mask is represented as below:
207 // mask: "user.displayName,photo"
210 // # Field Masks and Oneof Fields
212 // Field masks treat fields in oneofs just as regular fields. Consider the
213 // following message:
215 // message SampleMessage {
216 // oneof test_oneof {
218 // SubMessage sub_message = 9;
222 // The field mask can be:
231 // paths: "sub_message"
234 // Note that oneof type names ("test_oneof" in this case) cannot be used in
237 // ## Field Mask Verification
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.
243 // The set of field mask paths.
244 repeated string paths = 1;
git://repos.xcallymotion.com / motion2.git / blob