Protocol Buffers – Well-Known Types

Overview

FieldMask represents a set of symbolic field paths, for example: 

paths: "f.a"
paths: "f.b.d"

Here f represents a field in some root message, a and b fields in the message found in f, and d a field found in the message in f.b.

Field Masks in Projections

When used in the context of a projection, a response message or sub-message is filtered by the API to only contain those fields as specified in the mask.

Example 
f {
  a : 22
  b {
    d : 1
    x : 2
  }
  y : 13
}
z: 8

The result will not contain specific values for fields x,y and z:

f {
  a : 22
  b {
    d : 1
  }
}

Field Masks in Update Operations

A field mask in update operations specifies which fields of the targeted resource are going to be updated. The API is required to only change the values of the fields as specified in the mask and leave the others untouched.

Example

Given the target message:

f {
  b {
    d: 1
    x: 2
  }
  c: [1]
}

And an update message:

f {
  b {
    d: 10
  }
  c: [2]
}

With the field mask:

paths: ["f.b", "f.c"]

The result will be:

f {
  b {
    d: 10
    x: 2
  }
  c: [1, 2]
}

JSON Encoding of Field Masks

In JSON, a field mask is encoded as a single string where paths are separated by a comma. Fields name in each path are converted to/from lower-camel naming conventions. 

mask {
  paths: "user.display_name"
  paths: "photo"
}
{
  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) 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 unmappable.