legacy-libs/dialogflow/src/v2/doc/google/protobuf/doc_field_mask.js

   1 // Copyright 2019 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 //     https://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 // Note: this file is purely for documentation. Any contents are not expected
  16 // to be loaded as the JS file.
  17
  18 /**
  19  * `FieldMask` represents a set of symbolic field paths, for example:
  20  *
  21  *     paths: "f.a"
  22  *     paths: "f.b.d"
  23  *
  24  * Here `f` represents a field in some root message, `a` and `b`
  25  * fields in the message found in `f`, and `d` a field found in the
  26  * message in `f.b`.
  27  *
  28  * Field masks are used to specify a subset of fields that should be
  29  * returned by a get operation or modified by an update operation.
  30  * Field masks also have a custom JSON encoding (see below).
  31  *
  32  * # Field Masks in Projections
  33  *
  34  * When used in the context of a projection, a response message or
  35  * sub-message is filtered by the API to only contain those fields as
  36  * specified in the mask. For example, if the mask in the previous
  37  * example is applied to a response message as follows:
  38  *
  39  *     f {
  40  *       a : 22
  41  *       b {
  42  *         d : 1
  43  *         x : 2
  44  *       }
  45  *       y : 13
  46  *     }
  47  *     z: 8
  48  *
  49  * The result will not contain specific values for fields x,y and z
  50  * (their value will be set to the default, and omitted in proto text
  51  * output):
  52  *
  53  *
  54  *     f {
  55  *       a : 22
  56  *       b {
  57  *         d : 1
  58  *       }
  59  *     }
  60  *
  61  * A repeated field is not allowed except at the last position of a
  62  * paths string.
  63  *
  64  * If a FieldMask object is not present in a get operation, the
  65  * operation applies to all fields (as if a FieldMask of all fields
  66  * had been specified).
  67  *
  68  * Note that a field mask does not necessarily apply to the
  69  * top-level response message. In case of a REST get operation, the
  70  * field mask applies directly to the response, but in case of a REST
  71  * list operation, the mask instead applies to each individual message
  72  * in the returned resource list. In case of a REST custom method,
  73  * other definitions may be used. Where the mask applies will be
  74  * clearly documented together with its declaration in the API.  In
  75  * any case, the effect on the returned resource/resources is required
  76  * behavior for APIs.
  77  *
  78  * # Field Masks in Update Operations
  79  *
  80  * A field mask in update operations specifies which fields of the
  81  * targeted resource are going to be updated. The API is required
  82  * to only change the values of the fields as specified in the mask
  83  * and leave the others untouched. If a resource is passed in to
  84  * describe the updated values, the API ignores the values of all
  85  * fields not covered by the mask.
  86  *
  87  * If a repeated field is specified for an update operation, the existing
  88  * repeated values in the target resource will be overwritten by the new values.
  89  * Note that a repeated field is only allowed in the last position of a `paths`
  90  * string.
  91  *
  92  * If a sub-message is specified in the last position of the field mask for an
  93  * update operation, then the existing sub-message in the target resource is
  94  * overwritten. Given the target message:
  95  *
  96  *     f {
  97  *       b {
  98  *         d : 1
  99  *         x : 2
 100  *       }
 101  *       c : 1
 102  *     }
 103  *
 104  * And an update message:
 105  *
 106  *     f {
 107  *       b {
 108  *         d : 10
 109  *       }
 110  *     }
 111  *
 112  * then if the field mask is:
 113  *
 114  *  paths: "f.b"
 115  *
 116  * then the result will be:
 117  *
 118  *     f {
 119  *       b {
 120  *         d : 10
 121  *       }
 122  *       c : 1
 123  *     }
 124  *
 125  * However, if the update mask was:
 126  *
 127  *  paths: "f.b.d"
 128  *
 129  * then the result would be:
 130  *
 131  *     f {
 132  *       b {
 133  *         d : 10
 134  *         x : 2
 135  *       }
 136  *       c : 1
 137  *     }
 138  *
 139  * In order to reset a field's value to the default, the field must
 140  * be in the mask and set to the default value in the provided resource.
 141  * Hence, in order to reset all fields of a resource, provide a default
 142  * instance of the resource and set all fields in the mask, or do
 143  * not provide a mask as described below.
 144  *
 145  * If a field mask is not present on update, the operation applies to
 146  * all fields (as if a field mask of all fields has been specified).
 147  * Note that in the presence of schema evolution, this may mean that
 148  * fields the client does not know and has therefore not filled into
 149  * the request will be reset to their default. If this is unwanted
 150  * behavior, a specific service may require a client to always specify
 151  * a field mask, producing an error if not.
 152  *
 153  * As with get operations, the location of the resource which
 154  * describes the updated values in the request message depends on the
 155  * operation kind. In any case, the effect of the field mask is
 156  * required to be honored by the API.
 157  *
 158  * ## Considerations for HTTP REST
 159  *
 160  * The HTTP kind of an update operation which uses a field mask must
 161  * be set to PATCH instead of PUT in order to satisfy HTTP semantics
 162  * (PUT must only be used for full updates).
 163  *
 164  * # JSON Encoding of Field Masks
 165  *
 166  * In JSON, a field mask is encoded as a single string where paths are
 167  * separated by a comma. Fields name in each path are converted
 168  * to/from lower-camel naming conventions.
 169  *
 170  * As an example, consider the following message declarations:
 171  *
 172  *     message Profile {
 173  *       User user = 1;
 174  *       Photo photo = 2;
 175  *     }
 176  *     message User {
 177  *       string display_name = 1;
 178  *       string address = 2;
 179  *     }
 180  *
 181  * In proto a field mask for `Profile` may look as such:
 182  *
 183  *     mask {
 184  *       paths: "user.display_name"
 185  *       paths: "photo"
 186  *     }
 187  *
 188  * In JSON, the same mask is represented as below:
 189  *
 190  *     {
 191  *       mask: "user.displayName,photo"
 192  *     }
 193  *
 194  * # Field Masks and Oneof Fields
 195  *
 196  * Field masks treat fields in oneofs just as regular fields. Consider the
 197  * following message:
 198  *
 199  *     message SampleMessage {
 200  *       oneof test_oneof {
 201  *         string name = 4;
 202  *         SubMessage sub_message = 9;
 203  *       }
 204  *     }
 205  *
 206  * The field mask can be:
 207  *
 208  *     mask {
 209  *       paths: "name"
 210  *     }
 211  *
 212  * Or:
 213  *
 214  *     mask {
 215  *       paths: "sub_message"
 216  *     }
 217  *
 218  * Note that oneof type names ("test_oneof" in this case) cannot be used in
 219  * paths.
 220  *
 221  * ## Field Mask Verification
 222  *
 223  * The implementation of any API method which has a FieldMask type field in the
 224  * request should verify the included field paths, and return an
 225  * `INVALID_ARGUMENT` error if any path is duplicated or unmappable.
 226  *
 227  * @property {string[]} paths
 228  *   The set of field mask paths.
 229  *
 230  * @typedef FieldMask
 231  * @memberof google.protobuf
 232  * @see [google.protobuf.FieldMask definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/field_mask.proto}
 233  */
 234 const FieldMask = {
 235   // This is for documentation. Actual contents will be loaded by gRPC.
 236 };