Tellme Studio

Home MyStudio About Tellme
grammar element
Last Updated: 07-20-2009
VoiceXML 2.0
Specifies a permissible vocabulary for user interaction.

Syntax

<grammar
fetchhint = "string"
fetchtimeout = "string"
maxage = "seconds"
maxstale = "seconds"
mode = "string"
root = "string"
scope = "document_dialog"
src = "URI"
srcexpr = "ECMAScript_Expression"
tag-format = "string"
type = "encoding_type"
version = "string"
xml:base = "URI"
xml:lang = "string"
/>

Attributes
expr
DEPRECATED. Use srcexpr instead.
fetchhint
Defines when the interpreter context may retrieve grammar files from the server.
prefetch Grammar files may be prefetched.
safe Grammar files may only be fetched when needed, never before.
fetchtimeout
The time in seconds (s) or milliseconds (ms) for the VoiceXML interpreter to wait for content to be returned by the HTTP server before throwing an error.badfetch event. The fetchtimeout value is rounded down to the nearest whole second (e.g., 5700ms or 5.7s would be rounded down to 5s). If fetchtimeout has a value less than 1 second, it is reset to the default value. The default value is 15s.
maxage
Sends the max-age Cache-Control HTTP header along with the request for the specified resource. The header indicates that the document is willing to use content whose age is no greater than the specified time in seconds, unless maxstale is also provided.
Voice application developers should use extreme caution when setting this attribute. If used improperly, it could have an adverse affect on the performance of your application. You should only consider using this attribute in requests for frequently changing content (e.g. dynamically generated content) hosted on a misconfigured HTTP server that you do not control. To reduce load, some HTTP servers are configured to indicate to clients that content expires some arbitrary time in the future. In that case, set the maxage attribute to 0. If you do control the HTTP server, you should instead configure the HTTP server to omit the expires header and possibly to send the Cache-Control: no-cache header. The former requires the VoiceXML interpreter to check with the server before using any cached content. The latter requires the VoiceXML interpreter to not cache the fetched resource.
maxstale
Instructs the VoiceXML interpreter to send a max-stale Cache-Control header along with the HTTP request for the specified resource. The header indicates that the document is willing to use content that has exceeded its expiration time by no more than the specified number of seconds.
Voice application developers should use extreme caution when setting this attribute. If used improperly, your application may present stale content to users. If you do control the HTTP server, you should instead configure the HTTP server to send an expires header with a time in the distant future.
mode
Provides a hint to the interpreter regarding the mode of the contained grammar. Omitting the attribute indicates that the grammar contains both speech and DTMF values. To control what type of input the speech system will accept, use the inputmodes property.
dtmf The grammar contains values for DTMF input only. Specifying "dtmf" on a DTMF-only grammar bypasses the speech system and results in increased performance.
voice The grammar contains values for speech input only.
root
Required. Specifies the grammar rule to activate.
scope
The scope of the form-level grammar. This attribute overrides the value set by a form or menu element.
dialog The form-level grammar is active only within the parent form element or menu element.
document the form-level grammar is active in all dialogs of the active document. If the document is specified as the application root document, the grammar is active in all application documents.
src
The URI of an external grammar file.
srcexpr
An ECMAScript expression that evaluates to the URI of a grammar. Each time the VoiceXML interpreter is about to wait for user input, it evaluates the expression if the grammar is active.
tag-format
Specifies the content format for all tags within the grammar.
semantics/1.0 Defines the content of tags to be ECMAScript.
semantics/1.0-literals Defines the content of tags to be strings.
type
The MIME type of the grammar. If unspecified, the platform tries to determine the type dynamically.
application/srgs+xml The grammar is in the XML-based Speech Recognition Grammar Specification (SRGS).
version
Required. The version of the grammar specification. This should be set to "1.0".
xml:base
The base URI used to resolve relative references within the document.
xml:lang
The language and locale type for this grammar as defined in RFC 3066. If xml:lang is not specified, the value is inherited from the document hierarchy.

Parents
choice, field, form, link, record, transfer

Children
None.

Remarks
The grammar element lets you define an inline grammar or reference a built-in or external grammar. An inline grammar is a list of phrases and subgrammars included within the grammar element. You can define any number of inline grammars using SRGS syntax .
A grammar contained by the link element must be defined inline.
The attributes of the VoiceXML grammar element for an inline grammar are slightly different than the SRGS grammar element specified in an external grammar. For example, the VoiceXML grammar element does not include an xmlns attribute.
Grammars are cached based upon their URI. If a grammar's srcexpr attribute evaluates to a URI that exists in the grammar cache, the cached copy is used so long as it hasn't expired and the HTTP server reports that it doesn't have a newer version.
Gain additional performance by placing your grammars inline or by configuring your Web server to set the expires HTTP header on your grammars to a date in the distant future. Doing so allows the VoiceXML interpreter to eliminate querying the Web server for the last modification time of the grammar.
The src and srcexpr attributes are mutually exclusive.
If you do not specify a scope for a grammar, the scope is determined by its parent element. The scope attribute is only valid on grammars contained directly by a form.
If any of the fetchtimeout, fetchhint, maxage, or maxstale attributes is not specified for a grammar element, then the value of the fetchtimeout, grammarfetchhint, grammarmaxage, or grammarmaxstale property, respectively, is used.
Prior to revision 3, if you set the mode attribute to "voice", it is treated the same as if you had omitted the attribute. That is, the grammar is considered to contain both speech and DTMF values. In revision 3 and later, if you set mode to "voice", only speech input is recognized against that grammar.
Prior to revision 3, if a referenced grammar is empty, it is silently ignored. In revision 3 and later, the interpreter throws error.badfetch.
Prior to revision 3, if a grammar element contains a type attribute that specifies an unknown format, the VoiceXML interpreter throws error.badfetch. In revision 3 and later, the interpreter throws error.unsupported.format.
Prior to revision 3, if a scope attribute is specified for a grammar element that is a child of anything other than a form element, it is ignored. In revision 3 and later, in that situation the VoiceXML interpreter throws error.badfetch to the calling document.
Prior to revision 3, if a grammar for a form item contains no explicit result, but the caller says something that matches the grammar, the filled element is not executed. The prompt is immediately reexecuted. In revision 3 and later, the VoiceXML platform uses the raw text string for the utterance as the result.
Examples

Note that these examples are external grammars. To include them as an inline grammar within a VoiceXML document, remove the "<?xml ... ?>" and "xmlns=..." lines.

The following example defines a simple SRGS grammar that allows the user to specify a company department. Each department name maps to a three-digit department number. For example, the grammar returns the string "010" if the user says "sales". The grammar returns "040" if the user says "public relations" or "p r".

<?xml version= "1.0"?>

<grammar mode="voice"
         type="application/srgs+xml"
         root="root_rule"
         tag-format="semantics/1.0"
         version="1.0"
         xml:lang="en-US"
         xmlns="http://www.w3.org/2001/06/grammar">
  <rule id="root_rule" scope="public">
    <one-of>
      <item>
        <one-of>
          <item>
            sales
          </item>
        </one-of>
        <tag>out.dept = "010";</tag>
      </item>
      <item>
        <one-of>
          <item>
            marketing
          </item>
        </one-of>
        <tag>out.dept = "020";</tag>
      </item>
      <item>
        <one-of>
          <item>
            engineering
          </item>
        </one-of>
        <tag>out.dept = "030";</tag>
      </item>
      <item>
        <one-of>
          <item>
            public relations
          </item>
          <item>
            p r
          </item>
        </one-of>
        <tag>out.dept = "040";</tag>
      </item>
    </one-of>
  </rule>

</grammar>

The following example defines a SRGS grammar that allows the user to confirm or deny a request. For example, the grammar returns the string "yes" if the user says "yes", "yup", or "you got it" and returns the string "no" if the user says "no", "nope", or "no way."

<?xml version= "1.0"?>

<grammar mode="voice"
         root="root_rule"
         tag-format="semantics/1.0"
         version="1.0"
         xml:lang="en-US"
         xmlns="http://www.w3.org/2001/06/grammar">
  <rule id="root_rule" scope="public">
    <tag>str = "";</tag>
    <item>
      <one-of>
        <item>
          <ruleref uri="#LIB_YES_NO"/>
          <tag>str = rules.latest();</tag>
        </item>
      </one-of>
      <tag>out = str;</tag>
    </item>
  </rule>

  <rule id="LIB_YES_NO" scope="private">
    <one-of>
      <item>
        <one-of>
          <item>
            yes
          </item>
          <item>
            yeah
          </item>
          <item>
            yup
          </item>
          <item>
            sure
          </item>
          <item>
            okay
          </item>
          <item>
            correct
          </item>
          <item>
            right
          </item>
          <item>
            <item repeat="0-1">
              <item repeat="0-1">
                yes
              </item>
              that's
            </item>
            <one-of>
              <item>
                right
              </item>
              <item>
                correct
              </item>
            </one-of>
          </item>
          <item>
            <item repeat="0-1">
              yes
            </item>
            it is
          </item>
          <item>
            you got it
          </item>
          <item>
            yes i do
          </item>
          <item>
            yes i would
          </item>
          <item>
            yes it is correct
          </item>
        </one-of>
        <tag>out = "yes";</tag>
      </item>
      <item>
        <one-of>
          <item>
            no
          </item>
          <item>
            nope
          </item>
          <item>
            incorrect
          </item>
          <item>
            no way
          </item>
          <item>
            no it isn't
          </item>
          <item>
            <item repeat="0-1">
              no
            </item>
            <one-of>
              <item>
                it's
              </item>
              <item>
                that's
              </item>
            </one-of>
            not
            <one-of>
              <item>
                correct
              </item>
              <item>
                right
              </item>
            </one-of>
          </item>
          <item>
            <item repeat="0-1">
              no
            </item>
            it isn't
          </item>
          <item>
            <item repeat="0-1">
              no
            </item>
            it is not
          </item>
          <item>
            <item repeat="0-1">
              no
            </item>
            it's not
          </item>
          <item>
            no i don't
          </item>
          <item>
            no i do not
          </item>
          <item>
            no i wouldn't
          </item>
        </one-of>
        <tag>out = "no";</tag>
      </item>
    </one-of>
  </rule>

</grammar>

The following example defines a city/state grammar in SRGS that allows the user to say a limited number of U.S. cities and states, for example, "Boston, Massachusetts."

<?xml version= "1.0"?>

<grammar mode="voice"
         root="root_rule"
         tag-format="semantics/1.0"
         version="1.0"
         xml:lang="en-US"
         xmlns="http://www.w3.org/2001/06/grammar">
  <rule id="root_rule" scope="public">
    <tag>cs = "";</tag>
    <item>
      <one-of>
        <item>
          <ruleref uri="#LIB_CITY_STATE"/>
          <tag>cs = rules.latest();</tag>
        </item>
      </one-of>
      <tag>out.loc = cs;</tag>
    </item>
  </rule>

  <rule id="LIB_CITY_STATE" scope="private">
    <one-of>
      <item>
        boston
      </item>
      <item>
        massachusetts
        <tag>out = "boston_ma";</tag>
      </item>
      <item>
        fargo
      </item>
      <item>
        north
      </item>
      <item>
        dakota
        <tag>out = "fargo_nd";</tag>
      </item>
      <item>
        philadelphia
      </item>
      <item>
        pennsylvania
        <tag>out = "philadelphia_pa";</tag>
      </item>
      <item>
        san
      </item>
      <item>
        francisco
      </item>
      <item>
        california
        <tag>out = "san_francisco_ca";</tag>
      </item>
      <!-- and so on -->
    </one-of>
  </rule>

</grammar>


See Also
Understanding Grammars
Tellme Networks, Inc.Terms of ServicePrivacy PolicyGeneral Disclaimers