Grammar file structure
Like any XML document, a grammar file must begin with a header that specifies certain characteristics of the grammar. The main body of a grammar file consists of grammar rules that define the spoken words recognized by the grammar, and the corresponding variable values that will be returned for the recognized items.
Grammar file header
The header in a grammar file consists of the XML declaration, and the <grammar> element specifying the document language, root, and namespace:
<?xml version="1.0" encoding="UTF-8" ?>
<grammar xmlns="http://www.w3.org/2001/06/grammar"
version="1.0" xml:lang="en-US" root="YesNo"
tag-format="swi-semantics/1.0">
XML declaration and encoding type
The first element in the header is always the XML declaration. This element specifies the version of XML used in the document (1.0 or 1.1). It also specifies the encoding that applies for the document, which determines the language(s) that can or cannot be used.
The version and encoding are required attributes. Use any encoding appropriate to your preferences (for example, your computer setup, text-processing application, and so on). Recognizer does not care which encoding you use.
A short list of typical encodings for various languages appears below:
|
Encoding |
Description |
|---|---|
|
ISO-8859-1 |
Latin-1. Used for English, French, German, and Spanish. |
|
UTF-8 |
Used for all languages. |
|
UTF-16 |
Used for all languages. |
|
Big5 |
Used for Cantonese (ce-HK). |
|
GB |
Used for Mandarin (zh-TW). |
|
Shift-JIS and EUC-JP |
Used for Japanese. |
|
KSC and EUC-KR |
Used for Korean. |
Most languages can be represented in more than one encoding.
At runtime, Recognizer automatically converts the grammar file encoding into UTF-16 format using the International Components for Unicode (ICU) libraries. Visit the official website of the Unicode consortium at http://site.icu-project.org/.
Language, namespace, and semantic tag format
The second element in the header is the <grammar> element, whose attributes specify default information for the document. The required attributes are:
- xml:lang: Specifies the identifier for the default human language to be used, as defined in Request For Comments (RFC) document RFC 3066 on the IETF web site.
- Nuance supports a wide range of languages, as discussed in Setting the language in the grammar header. The language chosen must be compatible with the grammar encoding type.
- version: Specifies the version of GrXML (1.0).
- xmlns: Designates the grammar namespace. For GrXML grammars, this is always http://www.w3.org./2001/06/grammar.
- tag-format: defines the format that can be used for scripts within <tag> elements in the main body of the grammar to assign values.
The tag-format must be one of these strings:
|
Value |
Format of semantic tags |
|---|---|
|
swi-semantics/1.0 |
Nuance tag syntax (used if tag-format is not defined). This is known as "swi syntax" (for SpeechWorks International). |
|
semantics/1.0 |
W3C script tag syntax. |
|
semantics/1.0-literals |
W3C string literals tag syntax. |
- Strictly speaking, the tag-format attribute is not required if your grammar does not use the <tag> element. However, the vast majority of grammars do use <tag> to assign values, so Nuance strongly recommends that you specify the tag-format.
- Always point Nuance-specific GrXML attributes and elements (such as xmlns:nuance) to the namespace http://voicexml.nuance.com/grammar.
Optional attributes
There are also optional attributes to the <grammar> element:
- The root attribute specifies the default entry point into the grammar. When the grammar is invoked without specifying which rule to consult, Recognizer starts at this root rule. If no root rule is specified, Recognizer uses the first rule in the file.
- The mode attribute specifies the mode of the grammar: voice (speech recognition) and dtmf (DTMF). If not specified, the mode defaults to voice.
- The xml:base attribute specifies the starting location for all relative URLs contained in the grammar document. If not specified, the location of the current grammar file is used as the default.
Dictionaries
In some cases, the grammar may need to include words or phrases that Recognizer cannot parse normally. For example, a name may be said and spelled differently (like the city “Worcester”, which may be pronounced “wih-sta”).
You can use the <lexicon> element to import dictionaries that map utterances to matching text in the grammar file. For details, see User dictionaries.
Grammar file main body
The main section of a grammar file contains the rules that actually define the grammar: the spoken words and phrases to be recognized, and the values to be returned to the main application for each recognized item.
Rules
The main body of a grammar file consists of rules defined using the GrXML <rule> element. Each rule has a unique identifier. The words and phrases to be recognized by the rule appear as text within an <item> element or <token> element. These elements may themselves be nested within other GrXML elements:
- The <one-of> element presents a list of acceptable alternatives, only one of which is required to activate the rule.
- The <ruleref> element refers to another rule, as to a sub-routine.
- The <tag> element specifies actions to be carried out or values to be assigned to a variable; it may include a script written in the tag-format language.
When the user utters a word or phrase that is covered by the rule, the rule executes the actions, value assignments, or other code defined for that utterance.
Root rule
The root rule (the first rule in the file, unless otherwise specified in the header) serves as the default top-level rule. When the grammar is referenced without specifying the rule to look up, this root rule will be the first one consulted.
Rule scope
Each rule within the main body of a grammar file is assigned a scope, which indicates whether it can be referenced independently from external files (public), or only by another rule within the same grammar (private). All rules are private by default, unless specifically defined as public.
When the rule is public, its id attribute can be used as an anchor for references from other documents. For example, consider the following:
<grammar src="../grammars/universals.grxml#YesNo"/>
When this grammar element is invoked, it will refer directly to the public "YesNo" rule within the universals.grxml file, regardless of whether it is the file’s root rule.
Note: The root rule of a grammar file may be private. This means it cannot be referenced independently. However, it will still be used by default as the entry point to the grammar when the grammar file itself is invoked.
