AIP-3020

BII Schema Principles

Built-in intents (BIIs) allow third party developers to declare what their Actions can do. When a developer registers an Action for a BII, Google can then invoke that action to fulfill user requests matching that built-in intent.

Terminology

In the general principles below, we use the following terms:

• Built-in intents (BII): Fulfillment schemas that are used to call compatible APIs to perform Actions in response to a user query. Built-in intents allow your service to express its fulfillment capabilities to Google. By registering for built-in intents and mapping intent parameters to the fulfillment, it becomes possible for the Google Assistant to invoke the service to perform a task in response to natural language queries.

  A BII comprises an operation (full list below) and a Schema.org entity, otherwise known as a type. For example, CREATE_RESERVATION would be a BII for initiating a new reservation; this intent applies to various domains such as airline, hotel, restaurant, and other reservations.

• Operation: An Action which acts as a wrapper around a type.

• Type: The object on which the operation is acting upon.

General principles

Each BII should be treated like an API. While BIIs are technically fulfillment schemas, they fill the same role as an API, in that they tell third party developers about the structure of the request that their Action handles.

This AIP details principles for schema creation, with operation-specific and type-specific information, followed by a list of operations for BIIs.

Schema creation

• Existing Schema.org types and properties should be reused whenever the semantics needed already exist.
• The formula for naming a BII must be:
  • Operation + Type := VERB ["Operation" from list below] + '_' + NOUN ["Type" from Schema.org].
  • Types can be compound nouns which have more than one token. Types with more than one token have tokens separated by '_'.
    • Example: CREATE + '_' + MONEY_TRANSFER = CREATE_MONEY_TRANSFER
• BII names must be in CAPITAL_SNAKE_CASE (e.g. VERB_NOUN_NOUN).
• For more detail, see here.

Operations

• Operations comprise a small catalog of simple, generalizable verbs. These can be found at the bottom of the AIP under "List of BII Operations."
• There must not be overlap between the scope covered by any operations (mutual exclusivity).
  • Example: GET and CREATE do not overlap in scope; while both involve presenting an object, GET is for retrieving an existing object, while CREATE assumes no object yet exists and creates one.
• Operation + type combos should make semantic sense. If there is no operation that can work with the type chosen, either:
  • Choose a new type that is in semantic scope for the Action to attach to an existing operation, with a semantically sensible result.
    • Example: Say you want to fulfill a request for checking into a reservation. CREATE_CHECKIN does not seem to make the most semantic sense, since nothing is being created. Upon further thought, you decide to choose a different operation and call the BII UPDATE_RESERVATION instead, which makes more sense with the semantics of checking into a reservation.
  • Or, Create a new operation. Take this step only when there is no operation in the list that can cover the Action requested for the schema.
    • Example: Imagine you only had the operations START, STOP, and RESUME for controlling an ongoing activity. A fulfillment request comes in for temporarily stopping an ongoing activity of media playback but not terminating it. You try to create a BII called STOP_MEDIA, but then realize that this operation means the API must terminate the activity. You then create a new operation, PAUSE, which acts to "temporarily stop/pause activity", and does not overlap in scope with the existing operation, STOP. Your new BII is PAUSE_MEDIA.

Types

• Types must be defined as Schema.org types.
• The type must be the object upon which the operation is carried out.
• Semantic scope of the type should be generalizable, specificity may be in properties.
  • Example: Reservation is a type, which has a property named provider. The provider property specifies the service provider, service operator, or service performer. This ensures that any BII created using the type Reservation is generalizable to any service provider, and that the service provider information is still passed forward through Reservation’s property provider.
• Different types should take distinctly different properties.
• BIIs must be specific enough to avoid semantic ambiguity when calling an API. That is, we shouldn’t inadvertently trigger an Action that the user isn’t expecting.
  • Example: brokerage account vs. account: If we do not specify brokerage account, a GET_ACCOUNT BII could call an API that fulfills the Action for getting another sort of account’s information, such as a social media account. GET_BROKERAGE_ACCOUNT ensures the correct scope of financial account is retrieved by the API.
• The function prototype/set of parameters should be bound to the operation. That is, the operation decides the fulfillment boundaries of the Action.
• Each BII operation must take a Schema.org type.
• In BII schemas, the same Schema.org type, when combined with different verbs, may take different properties.
  • Example: GET_MESSAGE and CREATE_MESSAGE use a different but overlapping set of properties of Message.

Handling User Queries

• Generic/unresolved search criteria at the level of an object should be passed through the Description field.
• If a query argument can be recognized as a property of a type, it should be passed through as a property; if, on the other hand, an argument is recognized as just a description of the type, it should be passed through Description field.
  • Example: "find funky blues songs on YouTube" -> get_media_object(description="funky blues").

List of BII Operations