diff options
Diffstat (limited to 'src/google/protobuf/field_mask.proto')
-rw-r--r-- | src/google/protobuf/field_mask.proto | 90 |
1 files changed, 87 insertions, 3 deletions
diff --git a/src/google/protobuf/field_mask.proto b/src/google/protobuf/field_mask.proto index 908c8a86..76e09f39 100644 --- a/src/google/protobuf/field_mask.proto +++ b/src/google/protobuf/field_mask.proto @@ -37,7 +37,7 @@ option java_package = "com.google.protobuf"; option java_outer_classname = "FieldMaskProto"; option java_multiple_files = true; option objc_class_prefix = "GPB"; -option java_generate_equals_and_hash = true; +option go_package = "google.golang.org/genproto/protobuf/field_mask;field_mask"; // `FieldMask` represents a set of symbolic field paths, for example: // @@ -82,13 +82,13 @@ option java_generate_equals_and_hash = true; // } // // A repeated field is not allowed except at the last position of a -// field mask. +// paths string. // // If a FieldMask object is not present in a get operation, the // operation applies to all fields (as if a FieldMask of all fields // had been specified). // -// Note that a field mask does not necessarily applies to the +// Note that a field mask does not necessarily apply to the // top-level response message. In case of a REST get operation, the // field mask applies directly to the response, but in case of a REST // list operation, the mask instead applies to each individual message @@ -107,6 +107,58 @@ option java_generate_equals_and_hash = true; // describe the updated values, the API ignores the values of all // fields not covered by the mask. // +// If a repeated field is specified for an update operation, the existing +// repeated values in the target resource will be overwritten by the new values. +// Note that a repeated field is only allowed in the last position of a `paths` +// string. +// +// If a sub-message is specified in the last position of the field mask for an +// update operation, then the existing sub-message in the target resource is +// overwritten. Given the target message: +// +// f { +// b { +// d : 1 +// x : 2 +// } +// c : 1 +// } +// +// And an update message: +// +// f { +// b { +// d : 10 +// } +// } +// +// then if the field mask is: +// +// paths: "f.b" +// +// then the result will be: +// +// f { +// b { +// d : 10 +// } +// c : 1 +// } +// +// However, if the update mask was: +// +// paths: "f.b.d" +// +// then the result would be: +// +// f { +// b { +// d : 10 +// x : 2 +// } +// c : 1 +// } +// // In order to reset a field's value to the default, the field must // be in the mask and set to the default value in the provided resource. // Hence, in order to reset all fields of a resource, provide a default @@ -162,6 +214,38 @@ option java_generate_equals_and_hash = true; // mask: "user.displayName,photo" // } // +// # Field Masks and Oneof Fields +// +// Field masks treat fields in oneofs just as regular fields. Consider the +// following message: +// +// message SampleMessage { +// oneof test_oneof { +// string name = 4; +// SubMessage sub_message = 9; +// } +// } +// +// The field mask can be: +// +// mask { +// paths: "name" +// } +// +// Or: +// +// mask { +// paths: "sub_message" +// } +// +// Note that oneof type names ("test_oneof" in this case) cannot be used in +// paths. +// +// ## Field Mask Verification +// +// The implementation of any API method which has a FieldMask type field in the +// request should verify the included field paths, and return an +// `INVALID_ARGUMENT` error if any path is duplicated or unmappable. message FieldMask { // The set of field mask paths. repeated string paths = 1; |