Uh oh! We couldn’t find any match.

Please try other search keywords.

Bixby Developer Center


Extending Training with Vocabulary

Adding Vocabulary

Along with training that you add using the training tool, you can also add words and phrases that you want to associate with certain primitive concepts. (Structures similarly use patterns instead of vocabulary.)

Take, for example, a user who is looking to watch a movie tonight. However, instead of simply saying, "What movies are playing tonight", the user says, "What comedy is playing tonight?" In this case, you should ensure your capsule accounts for available movie genres.

To do this, create a new file of type Vocabulary within your capsule (File > New File) in the language-specific resource folder that vocab belongs to (in this case, en), and add vocabulary for the corresponding name concept, example.movie.MovieGenre:

vocab (example.movie.MovieGenre) {

If you need to add vocabulary for an enum type, format your vocab file as you would handle vocabulary for synonyms.


If you extend a type into another capsule, a new vocabulary file must still be created. Vocabulary is never inherited, even if you use extends or add role-of to a model.

Vocabulary for Synonyms

Vocabulary also comes in handy when you want to account for natural language words or phrases that are similar or equivalent.

For example, imagine a user wants to watch a funny movie tonight. They might ask Bixby:

"What comedy is playing tonight?"

But, they might ask:

"What funny movie is playing tonight?"

To anticipate similar or equivalent values (synonyms), you can add a vocabulary file that lists all of these words and phrases. Here's an example of a vocabulary entry that applies to comedy:

"comedy" { "comedy" "comedies" "funny" "funniest" }

With this vocabulary in place, utterances related to example.movie.MovieGenre can use "comedy" or "funny" interchangeably.


Notice that we have to include "comedy" twice: first as the name of the vocabulary entry, and again in the synonym values. If you don't add in the entry into the synonym values, Bixby won't be able to use the entry name.

This is what the complete vocab file looks like:

vocab (example.movie.MovieGenre) {
"animation" { "animation" "animations" "cartoon" "cartoons" }
"comedy" { "comedy" "comedies" "funny" "funniest" }
"documentary" { "documentary" "docudrama" "narrative" }

As shown below, handle vocabulary for enum types in the say way you add synonyms to a specified list of terms. For example, if you have the following enum:

enum (NewsType) { 
symbol (World News)
symbol (Local News)
symbol (National News)

The corresponding vocabulary file might be like this:

vocab (NewsType) {
// The vocab file has to define at least one value for enum if it is included in the vocab file.
// And this value does not have to be the same as the symbol
"World News" {"International"}
// But most use cases will probably require defining the symbol as part of the vocabulary.
"Local News" {"Local News" "local" "regional" "around me"} // Or define other values too

Vocabulary for Sorting

If your capsule allows for changing the sort order of results, you can link vocabulary entries to sort keys. For example, if you are working on a hotel booking capsule, you could sort search results by price.

This example lists all of the various ways a user could refer to expensive hotels (example.hotel.HighRate):

vocab (example.hotel.HighRate) {
$sort-desc {
"high priced"
"higher priced"
"more costly"
"more expensive"
"most costly"
"most expensive"

Vocabulary Classification

Vocabulary is considered closed if all the vocabulary belongs to a closed set of specified terms, and open otherwise.

For open matching, if you tag a word or phrase in a training example as a specific concept and it is not explicitly listed in the vocab, this matching is considered "out-of-vocabulary" (OOV).

Closed Types

The following types are considered "closed":

  • Enum: Vocabulary is required and any tagging must match one of the values specified in the vocab.
  • Boolean: Vocabulary is required and inherently set to true and false.
  • Qualified: Vocabulary is not allowed, but qualified types must follow the specific Regex pattern.
  • Numbers (Integer and Decimal): Vocabulary is required, but the platform provides these automatically for convenience.

Open Types

The following types are considered "open":

  • Name: Vocabulary is allowed, but any word can be matched to this type regardless. (OOV matching is acceptable.)
  • Text: Vocabulary is not allowed, so all matching is open. (OOV only.)

Limitations and Restrictions

This section discusses some of the limitations and restrictions for vocabulary.

Number of Entries Limitations

A capsule can have a maximum of 75,000 vocabulary entries total (across all concepts). Each concept can have up to 50,000 vocabulary entries.

Name Limitations

Bixby does not support pattern recognition in vocabulary. For example, let's assume you have a vocabulary list of MovieTitles and a vocabulary list of ActorNames. If your user has an utterance like "Show me Tom Cruise movies", unless you have "Tom Cruise" explicitly in your ActorNames vocab, Bixby won't be able to distinguish "Tom Cruise" as an actor or a movie title. You should keep adding more and better training examples. If that doesn't work, then it is probably not reasonable to have Bixby separate all those types for you. Instead, you should have a single type like SearchQuery and have your backend server handle doing the sorting and structured querying itself.

Boolean Case

The appropriate casing for boolean symbols in vocab is true and false.

Do use all lower case.

Don't do any of the following:

  • True, tRuE, or any form of mixed case
  • TRUE

Automatic Speech Recognition and Text-to-Speech

Automatic Speech Recognition (ASR) and Text-to-Speech (TTS) are useful Bixby capabilities for communicating with users. However, the natural language utterances you train and the vocabulary you add are only used in their specific capsule (although they might be used over time to help improve ASR and TTS performance).