AIP-3021

Type protos in Actions on Google APIs

Many Actions on Google fulfillment APIs need to represent typed data (datetime, money, etc.). In some cases, there are common components for representing these types.

Guidance

Fulfillment APIs must use the Actions on Google common types when applicable, and must not use alternative type protos. For example, an API which needs to represent a monetary amount must use google.type.Money, and must not use an alternative representation.

APIs may wrap existing types in new protos. This may be useful in order to define compound types, provide additional metadata, provide semantic signals (if the typed value was obtained from a user query), etc.

Actions on Google common types

The Actions on Google common types include all the protobuf types and API types defined in AIP-213, as well as all the protos in google.actions.type.*.

Adding new types

If a given API needs a type for which there is no existing common type, and the type is not conceptually specific to that API, and the type is well understood enough to be modeled in a permanent/unversioned way, then API author should consider proposing a new Actions on Google common type in google.actions.type.*.

The guidance in AIP-213 also applies to creating new Actions on Google common types. Specifically, API authors proposing new types should consider whether a new type should be a Google-wide common type rather than an Actions on Google common type. One exception to this is that new Actions on Google common types are not proposed by opening a GitHub ticket. Instead, Actions on Google API authors who want to create a new type should email the owners of the //google/actions/type directory directly.