# <grammar>

Description

Specifies a grammar for speech recognition or dtmf recognition.

Note that inline grammars that use the XML grammar format will be passed into the ASR engine as an XML document. When the VoiceXML page is first parsed by the interpreter, the inline grammar will be decoded. The interpreter will then re-encode the inline grammar into an XML document to pass to the ASR engine.

You must include a VXML grammar header in your VXML scripts. The correct format for an XML grammar header, according to the W3C specification, is:

xmlns="http://www.w3.org/2001/06/grammar"

Syntax

    <grammar
        xml:lang="language"
        src="URI"
        srcexpr="ECMAScript_Expression"
        expr="ECMAScript_Expression"
        scope="dialog" | "document"
        type="MIME_Type"
        mode="dtmf" | "voice" | "tdd"
        root="string"
        version="version"
        weight="positive floating_point"
        tag-format="string" | "URI"
        xml:base="URI"
        fetchhint="prefetch" | "safe"
        fetchtimeout="time_interval"
        maxage="integer"
        maxstale="integer">
      inline grammar
    </grammar>

Attributes

Attribute | Description
xml:lang | The language identifier of the grammar. The list of supported values for this attribute depends on the ASR engine being used. Optional.
src | The URI specifying the location of the grammar file. The URI can be one of the following formats: External grammar file: URL of the grammar file Built-in grammars: `builtin:grammar/type` (refer to `<field>` element for built-in types) Optional. Exactly one of src, srcexpr, expr, or an inline grammar must be specified.
srcexpr | An ECMAScript expression to be evaluated and used as the URI of the grammar file, as documented under `src`, above. Optional. Exactly one of src, srcexpr, expr, or an inline grammar must be specified. This VoiceXML 2.1 feature will be ignored if the `<vxml>` `version` attribute is set to a value lower than 2.1 (i.e. 2.0 or 1.0).
expr | An ECMAScript expression to be evaluated and used as the URI of the grammar file, as documented under `src`, above. Optional. Exactly one of src, srcexpr, expr, or an inline grammar must be specified. This attribute was added as an extension to VoiceXML 2.0. It can only be used if the `<vxml>` `version` attribute is set to a value lower than 2.1 (i.e. 2.0 or 1.0). When the `<vxml>` `version` attribute is set to 2.1, the `srcexpr` attribute must be used instead of `expr`; using `expr` will cause an `error.badfetch` event to be thrown.
scope | The scope of the grammar. This attribute can be defined only if the `<grammar>` element is the child of a `<form>` or `<menu>` element. Optional. (Defaults to dialog.) dialog - This grammar is only active within the form. document - This grammar is active throughout the document. If the current page is is an application root document, then the grammar is active throughout the application.
type | The MIME type of the grammar format. The supported types (and default values) for this attribute depend on the ASR engine being used.
mode | The mode of the grammar. Optional. (Defaults to voice.) voice - voice input dtmf - DTMF input (replaces the `<dtmf>` element) tdd - TDD input (not currently supported on the IP Media Server platform).
root | The root rule of the grammar. The default value depends on the ASR engine being used. Optional.
version | The version of the grammar. Optional. (Defaults to 1.0.)
weight | The weight of a grammar, which indicates the likelihood of using a grammar. This value is passed to the ASR engine and affects the actual recognition results returned by the ASR engine; it is not used by the VoiceXML interpreter to process recognition results after they have been returned by the ASR engine. Different ASR engines and VoiceXML platforms treat weights differently. This attribute is not supported for DTMF grammars and implicit grammars (i.e. `<grammar>` elements as children of `<option>` or `<choice>` tags). The range of values depends on the ASR engine, but it is usually 0.0 to 1.0. Optional. (Defaults to 1.0.)
tag-format | The format that will be used to define tags, for slot filling. Support for this attribute depends on the ASR engine being used.
xml:base | Declares the base URI from which relative URIs in the grammar are resolved. This base declaration has precedence over the `<vxml>` base URI declaration. Note that if a local declaration is omitted, the value will not be inherited down the document hierarchy. Also note that this attribute can only be used in external grammars, and support depends on the ASR engine being used. Optional.
fetchhint | Defines when the grammar file should be fetched. Optional. prefetch - grammar file may be downloaded when the page is loaded safe - only load the grammar file when needed
fetchtimeout | The length of time to wait for the grammar file to be fetched before throwing an `error.badfetch` event. Optional.
maxage | Indicates that this document is willing to use a cached copy of the grammar file only while the age of the cached copy is less than or equal to the number of seconds specified by this attribute. Optional.
maxstale | Indicates that this document is willing to use a cached copy of the grammar file that has exceeded its expiration time by as much as the number of seconds specified by this attribute. Optional.

Attribute Notes

- `src`, `expr`, or `srcexpr` will be used even if they are empty strings, and an external grammar fetch will be attempted (the resulting absolute URI will likely be an invalid URI and this will result in an `error.badfetch` event being thrown).
- Referencing an unsupported built-in grammar will result in an `error.unsupported.builtin` being thrown.
- If `scope` is used in a `<link>` grammar (and the VoiceXML page has at least one input field) or in an input item grammar, an `error.badfetch` will be thrown.
  If scope is used in a `<link>` grammar, but the VoiceXML page has no input fields, no warning will be logged and no error will be thrown.
- An `error.badfetch` event is thrown if more or less than one of `src`, `expr`, and an inline grammar are specified.

Parents

<choice>, <field>, <form>, <link>, <record>, <transfer>

Children

#PCDATA

Extensions

- Added `expr` attribute.
- Added "tdd" as value for `mode` attribute.

Limitations/Restrictions

- Currently, `<metadata>` and `<lexicon>` are not supported within an inline `<grammar>`.
- Speech grammars are not supported within a recording or a transfer. Please see `<record>` and `<transfer>` for details on how `<grammar mode="dtmf">` can be used as a child of those tags.
- TDD grammars have the same format as DTMF grammars, but their character set is different. The Baudot character set, minus the CR, LF, SP, and BACKSPACE characters, is supported for TDD grammars.
- SpeechWorks OSR does not support fetchhint.
- SpeechWorks OSR 1.x does not support the maxage and maxstale features; it supports caching. If maxage and/or maxstale are specified, an appropriate value for caching will be passed to the ASR engine instead.
- When using an XML speech grammar, the correct `xmlns` attribute value must be specified in the `<grammar>` tag, for the particular ASR engine the recognition session is using. Please refer to the ASR vendor's documentation for the acceptable value(s) for their grammar.
- Application developers should either make sure they explicitly specify the grammar type (ex., "application/grammar+xml") using the `type` attribute, or configure their application servers to return the correct MIME types for grammar files. Otherwise, the Dialogic IP Media Server will consider the grammar to be invalid.
- See additional notes.