Bixby Developer Center

Models are written in the Bixby Language, a simple declarative language with a structured, JSON-like format consisting of key/value pairs. Bixby Language has an emphasis on simplicity, and is designed to be suitable for both manual and automated creation.

Bixby Language Syntax

• Every declaration in Bixby Language begins with an alphanumeric key.
• Keys are optionally followed by a single parameter, which can be either of the following:
  • A string value.
  • An expression which evaluates to a string value.
• A key and, if it exists, its parameter, are sometimes referred to as a node.
• Keys are optionally followed by children, defined in blocks.
  • Blocks contain declarations which follow the same rules as above (keys followed by optional parameters and blocks).
  • The nodes inside a block are children of the parent nodes.
  • Blocks are contained in brackets, although there is a shortcut syntax for single-child nodes.
  • Some keys are only valid at the top level (that is, they have no parent); some keys are only valid as children of specific parent keys.
• In addition to declarations, Bixby Language supports expressions and conditionals.

This example from the Quick Start demonstrates the basic syntax:

structure (RollResultConcept) {
  description (The result object produced by the RollDice action)
  property (sum) {
    type (SumConcept)
    min (Required)
    max (One)
  }
  property (roll) {
    description (The list of results for each dice roll.)
    type (RollConcept)
    min (Required)
    max (Many)
  }
}

The key structure has a parameter of RollResultConcept, and is followed by a block. That block contains a description key with one parameter and two property keys, each of which has a parameter and each of which is followed by its own block.

In that snippet, we would describe structure as a top level key, and as the parent key of description and property. property is the parent key of description, type, min, and max. Bixby Language enforces a key hierarchy: only certain keys can be top level keys, and most keys can only be child keys of specific parents. The description key can be a child of both structure and property, but min and max could not be child keys of structure.

The Single Child Shortcut

When a parent key has a single child, instead of putting the child key in a block in brackets, you can write parent: child.

features {
  form-prompt
}

In that example, features has only one child key, form-prompt. So that code could be written more simply as:

features: form-prompt

If, however, features had two or more child keys, the code would need to be written with brackets.

The parent: child shortcut will work with key/value pairs for both the parent and the shortcut keys.

parent (value1): child (value2)

Expressions and Conditionals

Bixby Language supports conditionals such as if, switch, and choose. These follow the same convention as data: the key, a parameter (in this case a conditional test), and a block.

on-empty {
  if (exists(max(calories)) {
    drop (maxCalories)
  } else-if (exists(servings)) {
    drop (servings)
  }
}

Conditional tests, as well as the values in $expr(), are expressions; these are defined with Expression Language.

The single child shortcut can be used with conditionals.

// using blocks
switch (this) {
  case (FlowerArrangement) {
    template ("Flower Arrangement")
  }
  case (Bouquet) {
    template ("Bouquet")
  }
}

// using shortcut syntax
switch (this) {
  case (FlowerArrangement): template ("Flower Arrangement")
  case (Bouquet): template ("Bouquet")
}

For more on this topic, read Conditionals and Control Flows.

Values and Strings

All data values in Bixby Language are strings. Strings can be in one of two forms: quote delimited and unquoted literal.

• Quoted string values are delimited by the double quote mark ("). The following characters can be escaped in a string with a backslash (\):

  • \0: null character
  • \t: tab
  • \b: backspace
  • \n: newline
  • \f: form feed
  • \r: carriage return
  • \": double quote mark
  • \': single quote mark
  • \\: (unescaped) backslash

  In many contexts, quoted strings can contain Expression Language functions. This is a valid string with embedded EL:

  expression ("The next #{value(moonName)} is on #{value(date)}")

• Unquoted string values are delimited only by their enclosing parentheses:

  description (A flight reservation with a specific itinerary.)

  Unquoted strings are literal values. You cannot embed EL, and the backslash character will not escape the next character.

Intents

The intent key has a slightly different grammar, as some of its child nodes are not fixed keys in Bixby Language's schema.

if (exists(order)) {
  intent {
    goal: FindPods
    value: SpaceResort$expr(order.item.spaceResort)
  }
}

An intent has a goal and a value, just like an utterances training example does. (Utterances are converted to intents for processing by Bixby.) In the snippet above, the action FindPods is the child node of goal, and SpaceResort$expr(order.item.spaceResort) is the child node of value. That child node has a value of order.item.spaceResort.

This unusual handling is an artifact of the way Bixby processes intents, which have a more dynamic nature than Bixby Language's normal data model allows.

Bixby Language Conventions

In general, for all files in the *.bxb format, use the following conventions:

• Keys are lowercase-dash-separated
• Values are enclosed in parentheses
• Indent 2 spaces (using spaces, not tabs)

In addition, for modeling, use the following conventions:

• Concept and action names are of the form capsule.UpperCamelCaseName
• Property and input names are lowerCamelCase
• Constant values (such as cardinality and features) are UpperCamelCase

Models (concepts and actions) can be either qualified or unqualified:

• A qualified model refers to its organization name, capsule, and if fully qualified, version: viv.gratuity.CalculateTip, 2.5.5-viv.gratuity.ServiceBillTotal.
• An unqualified model leaves out organization, capsule, and version number: CalculateTip, ServiceBillTotal.

When referring to local concepts and actions (ones defined within the current capsule), it is preferable to use only the unqualified model name. This keeps your code, training utterances, and stories more portable, without tying them to a specific version number, organization, or capsule name.

Other Requirements

• Documents must be UTF-8 encoded. Null bytes (0x00) are not permitted.
• Tokens can be separated by one or more whitespace characters: space (0x20), tab (0x09), newline (0x0A), or carriage return (0x0D).
• All characters are valid for key names except whitespace characters and the following:
  ( ) { } " ' \
• String values can be either delimited by double quotes (") or unquoted:
  • Unquoted strings cannot contain the following characters { } " ' \
  • Quoted strings can contain special characters, but must be escaped by the backslash character (\): "The \"backslash\" character is \\"