Importing grammars

Any grammar can import other grammars as sub-elements by using the <ruleref> element. This import capability is especially useful when recognizing similar information in different contexts, because it allows re-use of a single modular grammar to collect the similar information. For example, a single “city” subgrammar can be used to recognize both the departure city and the destination city in a flight reservation grammar.

Issues in importing grammars

When importing one grammar into another, keep the following issues in mind:

  • Multiple languages: Grammars of any installed languages can be imported into each other. (See Controlling languages in a grammar.)
  • Mixed tag formats: A grammar that uses one script tag format can import a grammar that uses a different script tag format.
  • Nested grammars: A grammar definition may reference another grammar through the <ruleref> element. However, recursive rule references are not allowed: if rule A references rule B, then rule B cannot reference rule A.
  • Parameter precedence: When you import grammars containing <meta> elements, the rules of precedence for Recognizer parameters apply. See Rules of parameter precedence.
  • Differing modes: The two grammar modes are incompatible with each other, so voice and DTMF grammars cannot be imported into each other.

Static versus dynamic import

You can import grammars in static or dynamic mode. These terms refer to how the grammars are combined:

  • Static import means any combination of source and binary grammars that are bound together at compile time. If any component grammar changes, the entire static grammar must be recompiled.
  • Dynamic import means any combination of source and binary grammars where at least one of the component grammars is compiled and bound independently of the rest. Dynamic import is an advanced feature that allows the “dynamic linking” of components at runtime without requiring recompilation of the entire grammar.

Using <ruleref> to import a grammar

To include a grammar, specify the full URI of the grammar in the <ruleref>. For example, a birthday grammar could include a date grammar as follows: 

<ruleref uri="http://myuri/date.grxml#date"/>
 <tag>
  today = SWI_vars.today ? SWI_vars.today : 
  ’20090630’;
  if (date.DATE &gt; today) SWI_disallow=1;
 </tag>

Above, http://myuri/date.grxml specifies the URI of the grammar file, and #date specifies the rule to execute. Note that in order to specify the rule, it must be declared as public in the grammar.

In addition to importing the date grammar, the XML code above also executes a (swi-semantic) script to get the value of “today” from the application, from the URI that the application used to execute the grammar. If the application’s URI does not provide a value, a default of June 30, 2009 is set. Finally, the script disallows recognition of any date after the “today”.

To learn about passing variables between grammars, see Scripts, tags, and semantic interpretation.

You can reference built-in grammars as subgrammars. The convention for the public rule to execute is the name of the built-in grammar prefixed with an underscore (_). For example, to use the built-in date grammar: 

<ruleref uri="builtin:grammar/date#_date" />

From the information in the section on <ruleref> above, you might be tempted to employ similar scripting logic with a line such as the following: 

if (_date.DATE &gt; today) SWI_disallow=1;

This line produces an error, because the built-in grammar does not contain a DATE variable. Only MEANING variables are available in built-in grammars: so instead, you must refer to the _date.MEANING variable, like this: 

if (_date.MEANING &gt; today) SWI_disallow=1;

However, be aware the format of the MEANING variable is a character string rather than a number. The _date.MEANING may include characters—for example, if the caller only spoke a day and a month, the _date.MEANING may have question marks in the place of the year. This means that your application may have to be able to deal with these alphabetic characters.

You might encounter situations where a parent grammar imports a child that has a different tag format. For example, a grammar with W3C script syntax format could import a grammar with W3C string literals syntax format. This is known as mixed-format import.

The issues involved in a mixed-format import depend on the tag formats being mixed, and vary from case to case. For a detailed discussion with examples, see Importing grammars with different tag formats.

Compiling imported grammars

When you compile a static grammar, all of its imported grammars are included in the compilation automatically. This results in a self-contained binary grammar that is loaded, cached, activated, and recognized as a single grammar. However, if there are changes to one of the grammars that make up the whole, the entire grammar must be recompiled.

Recognizer also allows a more complicated scenario in which designated grammars are compiled and imported separately, after the main body of the grammar has been compiled. These dynamic imports minimize the runtime costs of compiling and loading grammars, and maximize the re-usability of modular grammars. If there are changes to one of the grammars, that grammar can be recompiled separately, and bound into the existing whole afterward.

Configuring via parameter grammars

You can set any Recognizer parameters by activating a parameter grammar. These grammars are XML files that list the parameters and their values. You can declare parameter grammars on a VoiceXML page. You cannot import parameter grammars into other grammars.

Parameter grammars can be used to tune individual recognition contexts by overriding any general or default settings.