AIP-3022

Built-in intent arguments and fulfillment APIs

Actions on Google's built-in intents (BIIs) are a fulfillment schema, and use Schema.org as a foreign vocabulary. BIIs are not a fulfillment API, and do not use the Actions on Google common types defined in AIP-3021.

Actions on Google has two types of generic fulfillment APIs:

• URI-based APIs like App Actions, which can only support string arguments.
• Google standard APIs, which support JSON primitive types like string and the Actions on Google common types.

These APIs do not support Schema.org JSON-LD objects. These APIs should support BII arguments by mapping them, or their properties, to the argument type schema they do support. For example, a BII argument of type MonetaryAmount may be mapped to an API field of type Money.

BII argument paths

Only certain Schema.org entity types should be mapped to a given common type. In order to support BII arguments with types that cannot be mapped to an appropriate type, APIs may support configuration via BII argument paths, strings which allow users to specify a property of a Schema.org entity which can be mapped to an appropriate type.

APIs which support BII argument paths should use the syntax defined in this section.

BII argument paths are dot-delimited strings that identify a specific Schema.org entity within the list of arguments to the BII.

For example, take the following hypothetical BII arguments grant and date:

{
  "grant": {
    "@context": "http://schema.org",
    "@type": "MonetaryGrant",
    "funder": {
      "@type": "Organization",
      "name": "Google"
    },
    "amount": {
      "@type": "MonetaryAmount",
      "currency": "USD",
      "value": 100
    }
  },
  "date": "2000-01-01"
}

There is no common type to which MonetaryGrant can be mapped, but the grant argument contains an amount property of type MonetaryAmount, which can be mapped to Money. This property can be referenced with the path string "grant.amount". Similarly, grant.name can be mapped to a string field.

A URI-based API which does not support Money would instead need to use the path strings "grant.amount.currency" and "grant.amount.value" to map grant.amount to two separate URI parameters.

On the other hand, date can be mapped to DateTime, and so the path string "date" would be sufficient for either URI-based APIs or string fields in JSON APIs.

Properties with multiple values

Since any Schema.org property may have multiple values, values other than the first may be referenced by indexing with square brackets. For example, take this hypothetical BII argument:

{
  "menuItem": {
    "@context": "http://schema.org",
    "@type": "MenuItem",
    "name": "pizza",
    "menuAddOn": {
      "@type": "MenuItem",
      "name": "pineapple"
    },
    "menuAddOn": {
      "@type": "MenuItem",
      "name": "extra cheese"
    }
  },
  "date": "2000-01-01"
}

In this example, the path "menuItem.menuAddOn[1].name" would evaluate to "extra cheese".

When there are no square brackets, the first value is assumed; using [0] is a no-op. That is, "menuItem.menuAddOn.name" and "menuItem.menuAddOn[0].name" are equivalent, and would both evaluate to "pineapple".

BII argument to common type mappings

Google standard APIs which support BII argument mapping should support at least these type mappings from Schema.org entity type to Actions on Google common types:

BII argument to JSON type mappings

Google standard APIs which support BII argument mapping should support at least these type mappings from Schema.org entity type to JSON type:

BII argument to string mappings

URI-based fulfillment APIs like App Actions can only map BII arguments to strings (URI parameters). These APIs should support mapping at least the following Schema.org entity types to URI parameters:

• Text
• Number
• Boolean
• Date
• DateTime
• Time