6   Nuance GSL Grammar Format

This chapter describes the syntax for defining a grammar using the Nuance Grammar Specification Language (GSL) format. This is a plain-text (non-XML) representation, developed by Nuance.

For detailed information on this format, Nuance developers can find the Grammar Developer's Guide at http://extranet.nuance.com. Nuance restricts access to its extranet to its partners and customers. Contact Nuance for access details.

Nuance's Grammar Developer's Guide describes how to create several different types of Nuance grammar--static grammars, just-in-time grammars, and other dynamic grammars. With the BeVocal VoiceXML interpreter, you cannot use static grammars or just-in-time grammars; you can only use other dynamic Nuance grammars.

Note: Nuance documentation uses slightly different terminology for various aspects of creating grammars than do the specifications for the other grammar formats supported by the BeVocal VoiceXML interpreter. In this document, we have primarily followed the terminology used by the W3C. In this chapter, we note the differences between that terminology and what you'll find in Nuance documentation.

The structure and possible content of a grammar may be slightly different depending on whether the grammar occurs inline in the <grammar> tag of a VoiceXML document or externally as a separate grammar file referenced by a URI from the <grammar> tag.

A grammar consists of a header followed by a body. The header is information relevant to defining the grammar as a whole. The body is a set of rule definitions that are used to match against user input. All the rules defined in the grammar are active only when the grammar is active.

This chapter contains the following sections:

Differences between Inline and External Definitions

An inline grammar is defined completely within the <grammar> element in a VoiceXML document. An external grammar, on the other hand, is defined completely in an external file and referenced in the VoiceXML document.

In an external grammar document, all rules must be named. In an internal grammar, however, if the grammar consists of exactly 1 rule, that rule does not have to have a name. If an internal grammar consists of multiple rules, however, all of the rules must have names.

The preferred extension for an external GSL grammar file is .gsl; the interpreter also recognizes the .grammar extension. For a compiled Nuance Grammar Object, the only recognized extension is .ngo. For information on creating Nuance Grammar Objects, see Compiled Grammar Files.

When you include a grammar definition directly in your VoiceXML document, you must take special care. GSL grammars use special characters not normally permitted in XML documents, such as angle brackets (< and >). Consequently, you should wrap your inline grammar as a section of CDATA:

 <grammar ...usage attributes...>
   <![CDATA[
   ...grammar header...
   ...grammar rule definitions...
   ]]>
 </grammar>

On the other hand, if you have an external GSL grammar file, the contents of that file should not be inside a CDATA section. Also, an external file should not contain a <grammar> element. So, an external grammar file simply looks like:

 ;GSL2.0
 ...grammar rule definitions...

The following sections describe exactly what goes in the header and body.

Comments

Comments may be placed anywhere in a grammar. You indicate the start of a comment with a semi-colon. Everything on the line following the semi-colon is ignored:

 ; this is a comment
 RuleName [rule expansion] ; this is a comment, after a non-comment

Reserved Words

The following strings are reserved. You cannot use them in your grammar as tokens or to define rule names:

 AND-n, OR-n, OP-n, KC-n, PC-n

where n is an integer.

Header Declarations

In most grammar formats, the header contains information relevant to the grammar as a whole. The GSL grammar format provides only a minimal amount of information in the header. So that you can easily compare this grammar format with others, this section describes both the header information available in GSL and what your options are for things it does not support but that are supported by ABNF and XML grammars.

Self-Identifying Header

Your GSL grammar can start with a self-identifying header, indicating the version of the grammar format. If it does, currently the header must be:

 ;GSL2.0

At present, this header is optional. For an external grammar file, it is strongly recommended that you include the header, however, as later versions may require it. For an inline GSL grammar, if your grammar is only a single rule fragment, do not include the header; if it is named rules, then you can include the header.

Language

The ABNF, XML, and JSGF grammar formats allow you to specify the language contained in the grammar. The GSL grammar format does not provide a way to specify the language of the grammar. However, if you refer to a GSL grammar with a rule reference in another grammar, you can specify the language of the GSL grammar in the rule reference. For information on how to do this in XML, see Rule References; in ABNF, see Rule References.

Grammar Mode

Both the ABNF and XML grammar formats restrict a single grammar to being either for recognizing speech input or for recognizing DTMF input. Those formats do not allow a single grammar to include both speech and DTMF; the mode of the grammar indicates whether it is for speech or for DTMF.

GSL does not have this restriction. Any GSL grammar can include both DTMF and speech tokens in the same grammar and even in the same rule.

Root Rule

A top-level grammar rule is one that the interpreter can use as the top-level syntax for matching spoken input. Nuance refers to a top-level rule in a grammar as the grammar and refers to other rules that occur in the grammar as subgrammars or grammar rules.

As described in Chapter  1, Using VoiceXML Grammars, a reference to a grammar may or may not specify a top-level rule. Consequently, all grammars need a way to specify the rule for the interpreter to use when you don't name one; this is called the root rule of the grammar. ABNF and XML allow you to explicitly name a rule as the root rule. In a GSL grammar, on the other hand, the root rule is always the first public rule in the grammar. For information on public rules, see Scoping of Rule Definitions.

Tag Format

The ABNF and XML grammar formats allow you to specify a document that describes the allowed format for semantic interpretations, or tags, in that format.

In GSL, this format is not under the control of the grammar writer. The GSL grammar format specifies the syntax for semantic interpretations provided in that grammar format. In GSL, they are called assignment commands; see Assignment Commands (Semantic Interpretations and Rule Variables).

Pronunciation Lexicon

The ABNF and XML grammar formats allow you to point to a lexicon document to provide extra pronunciation information to the interpreter.

GSL does not have syntax for pointing to a lexicon document.

Meta and HTTP-Equiv

The ABNF and XML grammar formats have syntax for providing metadata about the grammar itself. GSL does not have syntax for providing metadata.

Rule Definitions

The body of a grammar consists of a set of rule definitions or, simply, rules. The format of rule definitions can be slightly different, depending on whether they appear inline or in an external file.

Each rule definition can associate a rule name with a rule expansion or grammar description. The definition also defines the scope of the rule--whether it is local to the grammar in which it is defined or whether it may be referenced within other grammars.

Other grammar formats have special syntax for you to provide examples of matching user utterances. GSL does not have special syntax for this purpose. You simply put your examples in GSL comments.

Basic Rule Definition

A rule can have two parts:

You create rule expansions using a set of operators to combine words and/or other expressions. You use grammar assignment commands to associate an assignment operation to a particular rule expansion, either the top expression in the rule, or a component expression.

Because most grammars in VoiceXML identify a set of possible words that a user might say, the top-level rule expansion in a grammar rule is usually enclosed in square brackets ( [ ] ) to represent alternatives. The following example shows a simple named grammar rule:

 Fish [garibaldi "nassau grouper" trout]

This rule is named Fish and the rule expansion is the set of alternatives. This grammar is matched if the user says "Garibaldi", "Nassau Grouper", or "Trout".

Rule Names

The rule name is simply a string that identifies the rule. The rule name for each rule definition must be unique within the grammar. The same rule name may be used in multiple grammars.

In an external grammar, all rules must have names. In an internal grammar, if the grammar consists of exactly one rule, that rule does not need to have a name. In all other cases, all rules must have names.

In a rule reference (described in Rule References), you can use the rule name to specify a particular rule from which to start recognition.

A rule name is a case-sensitive string that starts with an uppercase letter. You can use the following characters within rule names:

Special Rules

GSL has 3 predefined rules:

 <special:passthrough>
 <special:roadblock>
 <special:resistor>

<special:NULL> is a synonym for <special:passthrough> and <special:VOID> is a synonym for <special:roadblock>. Your grammar must not contain rules with these names. The special rules have the following meanings:

Trigger = [<special:NULL> queen picasso]

Trigger = (<special:VOID> [queen picasso])

The format you use to refer to a special rule is a particular instance of a rule reference (see Rule References).

You can use the <special:NULL> and <special:VOID> rules together to dynamically change whether or not a rule is active. For example, assume your chamber of commerce application provides information that varies from season to season. During the winter, it answers questions about the amount of snow at the local ski resorts; during the summer, it answers questions about the hours of the local amusement parks; all year round, it answers questions about the plays at local theaters. You don't want the application to recognize questions about ski resorts during the summer.

You could completely change your grammars at every season. This might be difficult to maintain. You could ease the problem by organizing your grammars with a judicious combination of <special:VOID> and <special:NULL> rules. You would use the <special:VOID> and <special:NULL> rules to turn on and off recognition of the appropriate questions at the appropriate times of year.

If instead of completely not recognizing out of season requests, you simply want to indicate that those requests are much less likely, you could use of the special:resistor rule instead of <special:VOID>.

Scoping of Rule Definitions

Each defined rule has a scope of either private or public.

To mark a rule as public, the format is:

 RuleName:public ruleExpansion

There is not la special syntax for marking a rule as private. If no rules in the grammar are explicitly marked with :public, then all rules in the grammar are public. On the other hand, if any rule in the grammar is marked with :public, then all public rules must be so marked. In this case, rules that do not have :public are private.

The root rule in a GSL grammar is always the first public rule. In a grammar that has no rules explicitly marked as public (and so all rules are public), this means that the first rule in the grammar is the root rule. If the grammar explicitly marks some rules as public, the root rule is the first rule so marked.

For example, the following set of definitions creates one public rule named Snapper and two private rules named SnapperType and FishColors:

 SnapperType [mutton FishColors]
 FishColors [black gray red]
 Snapper:public (SnapperType snapper)

The root rule of this grammar is Snapper.

You should only make public the rules in your grammar that you want to be visible to other grammars. The use of private and public scope allows you to write more modular and maintainable grammars. For example, you can define a grammar that has a set internal "worker" rules that are combined to provide a smaller number of externally-accessible rules. Hiding worker rules prevents their accidental misuse.

Note: Do not confuse the scope of a rule with the scope of its containing grammar. The scope of the grammar indicates where in the VoiceXML application the grammar is active. The scope of the rule indicates whether or not the rule is available to other active grammars.

Rule Recursion

You can write a rule that refers to itself either directly or indirectly through a rule that it references.

 ; Rule that refers to itself directly
 Digits [Digit (Digit Digits)]
 Digit [0 1 2 3 4 5 6 7 8 9]
 
 ; Rule that indirectly refers to itself
 NounPhrase (Noun ?PrepositionalPhrase)
 PrepositionalPhrase (Preposition NounPhrase)

You should be careful in writing rules that refer to themselves. GSL does not support left-recursive rules. That is, it does not support defining a rule whose first sequential subcomponent contains itself:

 ; Legal
 Digits [Digit (Digit Digits)]
 Digits [(Digit Digits) Digit]
 
 ; Illegal
 Digits [(Digits Digit) Digit]
 Digits [Digit (Digits Digit)]

This restriction ensures that the interpreter doesn't get lost down an infinite path trying to match a rule.

Rule Expansions

A rule expansion is the part of a rule definition that actually describes what utterances match the rule. A rule expansion is a token, a rule reference, a semantic interpretation, or an arbitrarily complex combination of these things. For example, a rule expansion might express any of these ideas:

Tokens and rule references must be separated from each other by whitespace. Whitespace is optional between operators and their operands.

Language

The ABNF, XML, and JSGF grammar formats allow you to specify the language for a rule; the GSL grammar format does not. However, if you refer to a particular rule in a GSL grammar with a rule reference in another grammar, you can specify the language of the GSL rule in the rule reference. For information on how to do this in XML, see Rule References; in ABNF, see Rule References.

Tokens

A token is the part of a rule expansion that actually mentions a word that a user might speak or a DTMF key a user might press. Unlike the other grammar formats supported by the BeVocal VoiceXML interpreter, in GSL you can mix DTMF tokens and voice tokens in the same rule.

Voice Tokens

You can use the following characters within voice tokens, without requiring double quotes:

If you enclose a token in double quotes, you can use other special characters as well, with the exception of whitespace characters. For example, "new^york" is a valid token, but "new york" is not.

To improve the portability of your grammar, you should follow some simple rules:

DTMF Tokens

You can express valid touchtone sequences in a rule expansion using the following DTMF notation.

Key Press	DTMF Notation
0	dtmf-0
1	dtmf-1
2	dtmf-2
3	dtmf-3
4	dtmf-4
5	dtmf-5
6	dtmf-6
7	dtmf-7
8	dtmf-8
9	dtmf-9
*	dtmf-star
#	dtmf-pound

The following rule expansion allows either spoken or telephone keypad input:

 [(john smith)(dtmf-4 dtmf-9 dtmf-7 dtmf-3)]
   {<emp john_smith>}

The user can either say "John Smith" or use the touchtone sequence 4973 to create the same semantic interpretation for employee John Smith.

Rule References

Every rule in a grammar can have a name; if it does, that name is unique within the grammar. You can refer to a rule by name from within another rule either in the same or a different grammar definition. In summary, the formats for doing so are:

Reference to a...	Format
Local rule	RuleName
Local rule with a variable	RuleName:variableName
Root rule of a grammar identified by a URI	<grammarURI>
Named rule of a grammar identified by a URI	<grammarURI#RuleName>
Special rules	<special:passthrough>, <special:NULL> <special:roadblock>, <special:VOID> <special:resistor?weight=n>

See External Grammar Files for a description of how relative URIs work in grammar files. See Special Rules for information on the special rules.

When a grammar rule contains a rule reference, the effect is the same as if the referenced rule's rule expansion appeared in place of the rule name. For example, this PrimaryColors grammar rule refers to the Shades rule:

 PrimaryColors ( ?Shades [red blue green])
 Shades [ dark light ]

The PrimaryColors rule could also be written as:

 PrimaryColors [ ( ?[dark light] [red blue green] ) ]

Local Reference

A local rule reference is a reference to another rule in the same grammar. A local rule reference has one of the following two forms:

 RuleName 
 RuleName:variableName 

Both forms reference the rule named ruleName. The second form additionally specifies a variable named variableName to be set to any value returned by that rule. See Assignment Commands (Semantic Interpretations and Rule Variables) for information on variables.

An expansion can reference any grammar rule defined in the grammar that contains the rule expansion.

External Reference

You can reference rules defined in a different grammar. Here, the other grammar must be an external grammar which you can reference by its URI. You can optionally specify a specific rule in that grammar to use to start recognition. If you do not specify a rule to use, then the reference grammar must itself specify a root rule. The formats are:

 <grammarURI>
 <grammarURI#RuleName>

For example:

 ; Reference to the root rule of an external grammar
 <http://www.myCompany.com/grammars/fish.gram>
 
 ; Reference to a specific rule of an external grammar
 <../fish.gram#butterflies>

Note that you cannot use a rule reference in a GSL grammar to refer to a built-in grammar of the BeVocal VoiceXML interpreter. To refer to these built-in grammars, you must use the syntax described in Chapter  2, Using Built-in Grammars.

Combinations

GSL grammars combine tokens and rule references into more complex expressions. The basic types of combination are:

Type	Description
Alternation	A set of alternatives ("cat" or "dog" or "goat"). Enclosed in square brackets ( [ ] ).
Sequence	Multiple expressions that must all be said in a particular order ("great dane"). Enclosed in parentheses ( ( ) ).
Repetition	Repeat a single expression some number of times ("very" or "very very" or...). The * and + operators.
Optional	Special case of repeat 0 or 1 times (the "kitty" in match "kitty cat" or "cat"). The ? operator.
Weighting	Likelihood that an expression will be said. Indicated with ~ operator.

Alternatives

A set of alternatives matches if the caller says one of the things in the set. You specify a set of alternatives by surrounding them with square brackets ( [ ] ). Each alternative is simply another legal expression. For example:

 [ cat dog fish ]

You can have as many alternatives as you want in the set.

Sequence

A sequence is a set of expansions that must all be said in the order specified. You specify a set of alternatives by surrounding them with parentheses ( ( ) ). Some examples:

 (what is coral)    // sequence of tokens
 (Question Subject) // sequence of rule references
 (Subject is Type)  // sequence of tokens and rule references

Repeats

You can specify that an expression should be repeated some particular number of times. The syntax for this allows you to specify a variety of repetition types:

Syntax	Behavior
?expr	The expression is optional.
*expr	Repeat the expression 0 or more times.
+expr	Repeat the expression 1 or more times.

The repeat operator appears before the expression to which it is attached. For example:

 Gear = [mask fins snorkel booties gloves regulator]
 Action = [buy rent]
 MakeRequest = (I want to Action +Gear ?(and Gear) )

This set of rules matches a variety of utterances, including:

 I want to buy gloves.
 I want to rent mask and fins.
 I want to rent mask, fins, snorkel, and regulator.

Although you're allowed to create a rule that recognizes an unbounded number of expressions, users do not actually speak forever. The speech recognition will proceed more effectively if you are more careful and only indicate a limited range of occurrences. For example, the MakeRequest rule above allows the Gear rule to occur at least once, but any number of times more than that. It's unlikely that a user will request the same item more than once, so you could change the rule to allow Gear to be matched between 1 and 5 times:

 MakeRequest = (I want to Action Gear ?Gear ?Gear ?Gear ?Gear ?(and Gear) )

Weights or Probabilities

You can optionally assign transition weights, or probabilities for any number of the alternatives. A weight indicates how likely a particular alternative is. You specify a weight as a positive floating point number, such as 2, 2.5, 0.8, or .4. A weight of 1 is the same as not specifying a weight at all. A weight larger than 1 indicates that the alternative is more likely; a weight less than 1 indicates that the alternative is less likely. All probabilities in the set of alternatives are normalized to add to 1.0. If you don't specify any probabilities, all expressions are considered to be equally likely.

You specify a probability as follows:

 grammarExpression~probability

For example:

 [cat~3.1415 dog fish~.25]
 [fish~10 (angel fish)~2 anthia~0.1]

The first of these says that it is quite likely the user will say "cat", less likely but still fairly likely the user will say "dog", and not very likely the user will say "fish". The second says the user will almost certainly say "fish", might say "angelfish", and probably will not say "anthia".

You can also attach a probability to a repeat operator. The value indicates the probability of successive repetition of the repeated expression. Attaching a probability to a repeat operator is slightly different than attaching it to a standard expression:

Syntax	Description
?expr~.75	It is 75% certain that expr will be said once.
+expr~.75	Says nothing about the probability of expr being said the first time (since it must be said at least once). But, after expr has been said once, it is 75% certain that it will be repeated a second time. If it is said a second time, it is 75% certain it will be repeated a third time. And so on.
*expr~.75	As soon as this expression can be matched, it is 75% certain that it will be said a first time. Then, it is 75% certain that it will be repeated a second time. If it is said a second time, it is 75% certain it will be repeated a third time. And so on.

For example:

 ; the word "angel" is optional and is not very likely to occur.
 ?angel~0.25 fish
 
 ; the rule reference can occur 0 or more times and it is
 ; very likely it will occur more than once.
 *Digit~.8

Assignment Commands (Semantic Interpretations and Rule Variables)

You use grammar assignment commands to associate an assignment operation with a particular rule expansion, either the top expression in the rule, or a component expression. The assignment commands for a rule expansion are enclosed in curly braces ( { } ) and immediately follow the associated rule expansion. The curly braces can enclose one or more individual assignment commands.

Each time the speech-recognition engine encounters a word or phrase that matches an expression in an active grammar, it flags a match and executes any assignment command associated with the expression.

An individual assignment command is either a slot-filling command or a return command:

<slotname value> 

return (value)

The value expression in an assignment command can be a literal value, a variable expression, or a function call, as described in sections below.

Slot-Filling Command Example

The following grammar has 2 different slot-filling commands:

 ;GSL 2.0;
 ColoredOjbect:public (Color Object)
 Color [
   [red pink]      { <color red> }
   [yellow canary] { <color yellow> }
   [green khaki]   { <color green> }
 ]
 Object [
   [truck car]    { <object vehicle> }
   [ball block]   { <object toy> }
   [shirt blouse] { <object clothing> }
 ]

This grammar recognizes phrases such as "yellow shirt" or "canary blouse". For both of those phrases, it will return the same semantic interpretation:

 {
   color: yellow;
   object: clothing;
 }

The VoiceXML interpreter will use this semantic interpretation to set the slots of active elements. This simple example allows your grammar to accept synonyms and return a more canonical result that can be used later in your VoiceXML application. See Setting Input Variables for information on how the interpreter uses the semantic interpretation.

Return Command Example

The following example returns a value from the City subrule to the Flight rule:

 Flight:public [
   ( [from leaving] City:frCity )     { <origin $frCity> }
   ( [to (arriving in)] City:toCity ) { <destination $toCity> }
 ]
 
 City [ 
   atlanta { return ("Atlanta") }
   chicago { return ("Chicago") }
   dallas  { return ("Dallas") }
 ]

Literal Values

A literal value is an integer or a quoted or unquoted string. A literal value is evaluated as follows:

As the preceding list suggests, values that can be interpreted as integers are treated as integers. For example, the value 01 in the following grammar rule can be interpreted as an integer:

 DigitValue [ 
   ([zero oh] one) { return (01) }
   ...
 ]

If the user says "oh one", the DigitValue rule will return the integer 1.

If you want an integer value to be treated as a string, you can enclose it in double quotes, for example:

 DigitString [
   ([zero oh] one) { return ("01") }
   ...
 ]

If the user says "oh one", the DigitString rule will return the string "01".

Variable Expressions

As shown in the return command example, if a rule includes a rule reference to a subrule and that rule reference specifies a variable variableName, an assignment command of the containing rule can use a variable expression of the form:

 $variableName

This expression evaluates to the value returned from the referenced rule.

A special variable, string, is used to capture the portion of the utterance that matched a rule expansion; its value can be obtained with expression:

 $string

For example, the following rule accepts the name of a day of the week and sets the day property to the word that the user said:

 DayOfWeek [ 
   sunday monday tuesday wednesday 
   thursday friday saturday
 ] { <day $string>}

Function Calls

You can use a function call to an arithmetic or string function to compute the value in an assignment command. The parameters to the function can be value literals, variable expressions, or other function calls.

The following integer and string functions are available for use in value expressions. The third column indicates the default value for a parameter that is undefined.

Function	Description	Default Parameter Value
add	Adds two integers.	0
sub	Subtracts the second integer from the first.	0
mul	Multiplies two integers together.	1
div	Divides the first integer by the second and returns the truncated result.	0 for first parameter; 1 for second parameter
neg	Returns the negative or positive inverse of an integer.	0
strcat	Concatenates two strings, but may be nested to effectively concatenate any number of strings, for example: strcat($a1 strcat($a2 $a3))	"" (empty string)

The following example illustrates how functions can be used to compute the value of the number input variable from values returned by subrules.

 TwoDigit [ 
   (Digit:n1 Digit:n2)                    { <number add((mul(10 $n1)) $n2) } 
   TeenAndTen:n                           { <number $n> }
   (DecadeFromTwenty:n1 ?NonZeroDigit:n2) { <number add($n1 $n2)> }
 ]
 
 Digit [
   [zero oh]      { return(0) }
   NonZeroDigit:d { return($d) }
 ]
 
 NonZeroDigit [
   one  { return(1) }
   two  { return(2) }
   ...
   nine { return(9) }
 ]
 
 TeenAndTen [
   ten      { return(10) }
   eleven   { return(11) }
   ...
   nineteen { return(19) }
 ]
 
 DecadeFromTwenty [
   twenty { return(20) }
   thirty { return(30) }
   ...
   ninety { return(90) }
 ]

Notice in the TwoDigit rule, the third rule expansion has an optional element. If the user said "twenty", the value of n2 would be undefined. Since the default value for the add function is zero, the result will be correct (20 + 0).

Café Home | Developer Agreement | Privacy Policy | Site Map | Terms & Conditions Part No. 520-0004-02 | © 1999-2005, BeVocal, Inc. All rights reserved | 1.877.33.VOCAL