Protocol Buffers Well-Known Types

Index

• Any (message)
• Api (message)
• BoolValue (message)
• BytesValue (message)
• DoubleValue (message)
• Duration (message)
• Empty (message)
• Enum (message)
• EnumValue (message)
• Field (message)
• Field.Cardinality (enum)
• Field.Kind (enum)
• FieldMask (message)
• FloatValue (message)
• Int32Value (message)
• Int64Value (message)
• ListValue (message)
• Method (message)
• Mixin (message)
• NullValue (enum)
• Option (message)
• SourceContext (message)
• StringValue (message)
• Struct (message)
• Syntax (enum)
• Timestamp (message)
• Type (message)
• UInt32Value (message)
• UInt64Value (message)
• Value (message)

Well-Known Types that end in “Value” are wrapper messages for other types,such asBoolValue andEnumValue. These are now obsolete. The only reasons touse wrappers today would be:

• Wire compatibility with messages that already use them.
• If you want to put a scalar value into anAny message.

In most cases, there are better options:

• For new messages, it’s better to use regular explicit-presence fields(optional in proto2/proto3, regular field in edition >= 2023).
• Extensions are generally a better option thanAny fields.

Any

Any contains an arbitrary serialized message along with a URL that describesthe type of the serialized message.

JSON

The JSON representation of anAny value uses the regular representation of thedeserialized, embedded message, with an additional field@type which containsthe type URL. Example:

packagegoogle.profile;messagePerson{stringfirst_name=1;stringlast_name=2;}

{"@type":"type.googleapis.com/google.profile.Person","firstName":<string>,"lastName":<string>}

If the embedded message type is well-known and has a custom JSON representation,that representation will be embedded adding a fieldvalue which holds thecustom JSON in addition to the@type field. Example (for messagegoogle.protobuf.Duration):

{"@type":"type.googleapis.com/google.protobuf.Duration","value":"1.212s"}

Api

Api is a light-weight descriptor for a protocol buffer service.

BoolValue

Wrapper message forbool.

The JSON representation forBoolValue is JSONtrue andfalse.

BytesValue

Wrapper message forbytes.

The JSON representation forBytesValue is JSON string.

DoubleValue

Wrapper message fordouble.

The JSON representation forDoubleValue is JSON number.

Duration

A Duration represents a signed, fixed-length span of time represented as a countof seconds and fractions of seconds at nanosecond resolution. It is independentof any calendar and concepts like "day" or "month". It is related toTimestamp in that the difference between two Timestamp values is a Duration andit can be added or subtracted from a Timestamp. Range is approximately +-10,000years.

Example 1: Compute Duration from two Timestamps in pseudo code.

Timestampstart=...;Timestampend=...;Durationduration=...;duration.seconds=end.seconds-start.seconds;duration.nanos=end.nanos-start.nanos;if(duration.seconds<0&&duration.nanos>0){duration.seconds+=1;duration.nanos-=1000000000;}elseif(duration.seconds>0&&duration.nanos<0){duration.seconds-=1;duration.nanos+=1000000000;}

Example 2: Compute Timestamp from Timestamp + Duration in pseudo code.

Timestampstart=...;Durationduration=...;Timestampend=...;end.seconds=start.seconds+duration.seconds;end.nanos=start.nanos+duration.nanos;if(end.nanos<0){end.seconds-=1;end.nanos+=1000000000;}elseif(end.nanos>=1000000000){end.seconds+=1;end.nanos-=1000000000;}

The JSON representation forDuration is aString that ends ins toindicate seconds and is preceded by the number of seconds, with nanosecondsexpressed as fractional seconds.

Empty

A generic empty message that you can re-use to avoid defining duplicated emptymessages in your APIs. A typical example is to use it as the request or theresponse type of an API method. For instance:

serviceFoo{rpcBar(google.protobuf.Empty)returns(google.protobuf.Empty);}

The JSON representation forEmpty is empty JSON object{}.

Enum

Enum type definition

EnumValue

Enum value definition.

Field

A single field of a message type.

Cardinality

Whether a field is optional, required, or repeated.

Kind

Basic field types.

FieldMask

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

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

Heref represents a field in some root message,a andb fields in themessage found inf, andd a field found in the message inf.b.

Field masks are used to specify a subset of fields that should be returned by aget operation (aprojection), or modified by an update operation. Field masksalso have a custom JSON encoding (see below).

Field Masks in Projections

When aFieldMask specifies aprojection, the API will filter the responsemessage (or sub-message) to contain only those fields specified in the mask. Forexample, consider this "pre-masking" response message:

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

After applying the mask in the previous example, the API response will notcontain specific values for fields x, y, or z (their value will be set to thedefault, and omitted in proto text output):

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

A repeated field is not allowed except at the last position of a field mask.

If aFieldMask object is not present in a get operation, the operation appliesto all fields (as if a FieldMask of all fields had been specified).

Note that a field mask does not necessarily apply to the top-level responsemessage. In case of a REST get operation, the field mask applies directly to theresponse, but in case of a REST list operation, the mask instead applies to eachindividual message in the returned resource list. In case of a REST custommethod, other definitions may be used. Where the mask applies will be clearlydocumented together with its declaration in the API. In any case, the effect onthe returned resource/resources is required behavior for APIs.

Field Masks in Update Operations

A field mask in update operations specifies which fields of the targetedresource are going to be updated. The API is required to only change the valuesof the fields as specified in the mask and leave the others untouched. If aresource is passed in to describe the updated values, the API ignores the valuesof all fields not covered by the mask.

In order to reset a field’s value to the default, the field must be in the maskand set to the default value in the provided resource. Hence, in order to resetall fields of a resource, provide a default instance of the resource and set allfields in the mask, or do not provide a mask as described below.

If a field mask is not present on update, the operation applies to all fields(as if a field mask of all fields has been specified). Note that in the presenceof schema evolution, this may mean that fields the client does not know and hastherefore not filled into the request will be reset to their default. If this isunwanted behavior, a specific service may require a client to always specify afield mask, producing an error if not.

As with get operations, the location of the resource which describes the updatedvalues in the request message depends on the operation kind. In any case, theeffect of the field mask is required to be honored by the API.

Considerations for HTTP REST

The HTTP kind of an update operation which uses a field mask must be set toPATCH instead of PUT in order to satisfy HTTP semantics (PUT must only be usedfor full updates).

JSON Encoding of Field Masks

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

As an example, consider the following message declarations:

messageProfile{Useruser=1;Photophoto=2;}messageUser{stringdisplay_name=1;stringaddress=2;}

In proto a field mask forProfile may look as such:

mask{paths:"user.display_name"paths:"photo"}

In JSON, the same mask is represented as below:

{mask:"user.displayName,photo"}

FloatValue

Wrapper message forfloat.

The JSON representation forFloatValue is JSON number.

Int32Value

Wrapper message forint32.

The JSON representation forInt32Value is JSON number.

Int64Value

Wrapper message forint64.

The JSON representation forInt64Value is JSON string.

ListValue

ListValue is a wrapper around a repeated field of values.

The JSON representation forListValue is JSON array.

Method

Method represents a method of an api.

Mixin

Declares an API to be included in this API. The including API must redeclare allthe methods from the included API, but documentation and options are inheritedas follows:

• If after comment and whitespace stripping, the documentation string of theredeclared method is empty, it will be inherited from the original method.

• Each annotation belonging to the service config (http, visibility) which isnot set in the redeclared method will be inherited.

• If an http annotation is inherited, the path pattern will be modified asfollows. Any version prefix will be replaced by the version of the includingAPI plus theroot path if specified.

Example of a simple mixin:

packagegoogle.acl.v1;serviceAccessControl{// Get the underlying ACL object.rpcGetAcl(GetAclRequest)returns(Acl){option(google.api.http).get="/v1/{resource=**}:getAcl";}}packagegoogle.storage.v2;serviceStorage{//       rpc GetAcl(GetAclRequest) returns (Acl);// Get a data record.rpcGetData(GetDataRequest)returns(Data){option(google.api.http).get="/v2/{resource=**}";}}

Example of a mixin configuration:

apis:- name: google.storage.v2.Storage  mixins:  - name: google.acl.v1.AccessControl

The mixin construct implies that all methods inAccessControl are alsodeclared with same name and request/response types inStorage. A documentationgenerator or annotation processor will see the effectiveStorage.GetAcl methodafter inheriting documentation and annotations as follows:

serviceStorage{// Get the underlying ACL object.rpcGetAcl(GetAclRequest)returns(Acl){option(google.api.http).get="/v2/{resource=**}:getAcl";}...}

Note how the version in the path pattern changed fromv1 tov2.

If theroot field in the mixin is specified, it should be a relative pathunder which inherited HTTP paths are placed. Example:

apis:- name: google.storage.v2.Storage  mixins:  - name: google.acl.v1.AccessControl    root: acls

This implies the following inherited HTTP annotation:

serviceStorage{// Get the underlying ACL object.rpcGetAcl(GetAclRequest)returns(Acl){option(google.api.http).get="/v2/acls/{resource=**}:getAcl";}...}

NullValue

NullValue is a singleton enumeration to represent the null value for theValue type union.

The JSON representation forNullValue is JSONnull.

Option

A protocol buffer option, which can be attached to a message, field,enumeration, etc.

SourceContext

SourceContext represents information about the source of a protobuf element,like the file in which it is defined.

StringValue

Wrapper message forstring.

The JSON representation forStringValue is JSON string.

Struct

Struct represents a structured data value, consisting of fields which map todynamically typed values. In some languages,Struct might be supported by anative representation. For example, in scripting languages like JS a struct isrepresented as an object. The details of that representation are describedtogether with the proto support for the language.

The JSON representation forStruct is JSON object.

Syntax

The syntax in which a protocol buffer element is defined.

Timestamp

A Timestamp represents a point in time independent of any time zone or calendar,represented as seconds and fractions of seconds at nanosecond resolution in UTCEpoch time. It is encoded using the Proleptic Gregorian Calendar which extendsthe Gregorian calendar backwards to year one. It is encoded assuming all minutesare 60 seconds long, i.e. leap seconds are “smeared” so that no leap secondtable is needed for interpretation. Range is from 0001-01-01T00:00:00Z to9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that wecan convert to and from RFC 3339 date strings. Seehttps://www.ietf.org/rfc/rfc3339.txt.

The Timestamp type is encoded as a string in the RFC 3339 format:“{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z”, where{year} isalways expressed using four digits while{month},{day},{hour},{min},and{sec} are zero-padded to two digits each. The fractional seconds, whichcan go up to 9 digits (that is, up to 1 nanosecond resolution), are optional.The “Z” suffix indicates the timezone (“UTC”); the timezone is required. Aproto3 JSON serializer should always use UTC (as indicated by “Z”) when printingthe Timestamp type and a proto3 JSON parser should be able to accept both UTCand other timezones (as indicated by an offset).

Example 1: Compute Timestamp from POSIXtime().

Timestamptimestamp;timestamp.set_seconds(time(NULL));timestamp.set_nanos(0);

Example 2: Compute Timestamp from POSIXgettimeofday().

structtimevaltv;gettimeofday(&tv,NULL);Timestamptimestamp;timestamp.set_seconds(tv.tv_sec);timestamp.set_nanos(tv.tv_usec*1000);

Example 3: Compute Timestamp from Win32GetSystemTimeAsFileTime().

FILETIMEft;GetSystemTimeAsFileTime(&ft);UINT64ticks=(((UINT64)ft.dwHighDateTime)<<32)|ft.dwLowDateTime;// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.Timestamptimestamp;timestamp.set_seconds((INT64)((ticks/10000000)-11644473600LL));timestamp.set_nanos((INT32)((ticks%10000000)*100));

Example 4: Compute Timestamp from JavaSystem.currentTimeMillis().

longmillis=System.currentTimeMillis();Timestamptimestamp=Timestamp.newBuilder().setSeconds(millis/1000).setNanos((int)((millis%1000)*1000000)).build();

Example 5: Compute Timestamp from current time in Python.

now=time.time()seconds=int(now)nanos=int((now-seconds)*10**9)timestamp=Timestamp(seconds=seconds,nanos=nanos)

Type

A protocol buffer message type.

UInt32Value

Wrapper message foruint32.

The JSON representation forUInt32Value is JSON number.

UInt64Value

Wrapper message foruint64.

The JSON representation forUInt64Value is JSON string.

Value

Value represents a dynamically typed value which can be either null, a number,a string, a boolean, a recursive struct value, or a list of values. A producerof value is expected to set one of that variants, absence of any variantindicates an error.

The JSON representation forValue is JSON value.