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  }