VoiceXML 2.1 Development Guide

| TOC

grXML Basics

XML Grammars may either be defined in an external file, or inside the vxml code itself, although any non-parseable characters will need to be enclosed in a CDATA block in order for the application to run properly. A good point to keep in mind is that the VoiceXML platform has hard-coded limits of up to 30 seconds as well as 50 words per utterance. These values were chosen as realistic "real world" upper bounds for speech recognition applications. Also bear in mind that declaring a grammar 'type' is always recommended, in order to keep your code as portable as possible across multiple platforms. A breakdown of a simple XML grammar is as follows:


 <?xml version= "1.0"?>

    <grammar xmlns="http://www.w3.org/2001/06/grammar" xml:lang="en-US"
                    root = "MYRULE">

      <rule id="MYRULE">
        <one-of>
          <item> philly <tag>out.F_1="Philadelphia";</tag> </item>
        </one-of>
      </rule>
    </grammar>

Markup	Explanation
`MYRULE`	(Top Level Rulename) This is the sub-file that the grammar src refereneces
`philly`	(User Utterance) The expected phrase from the caller that a grammar will get a valid match upon
`F_1`	(Slot Name) The field or slot in the application that the return result will be sent to upon a match
`"Philadelphia"`	(Returned Result) A user-defined value to be returned upon a successful recognition

Grammar Scoping

Grammars can be given explicit scoping instructions via the 'scope' attribute. A grammar declared as 'document' scope will be considered active throughout the document, while a grammar declared as 'dialog' will only be active while in that particular form.

Grammars that have been given a scope other than 'dialog' must have a slotname defined and a <filled> handler in order to process correctly. The best practice for using an application scoped grammar is to utilize the <link> tag in the application root document. Links, unlike grammars, cannot declare a scope, and are always considered to be document/application scoped.

Rule Scoping

Note that XML grammar rules also define a scope as well, either 'public' or 'private'. Selecting a scope of 'public' allows the grammar to be accessed by other grammars that may be active in the application, (via the 'ruleref' attribute), while selecting a scope of 'private' disallows the rule from being referenced by other grammars.

Rulenames and Rulesets

External XML grammars must always have a top level rulename defined in the grammars 'rule' attributes, and within the rules 'id' attribute attribute, as demonstrated below:

<grammar xmlns="http://www.w3.org/2001/06/grammar" xml:lang="en-US" root = "MYRULENAME">
  <rule id="MYRULENAME">
    ...

Inline subgrammars must also have a top level rulename and be referenced by this in the src attribute, (see the 'Inline Subgrammars' section). Rulenames must also start with a capital letter; while it is good coding practice to have your rulenames in all capitals, it is not absolutely neccessary.

XML Grammar Filesize

When constructing a grXML grammar for the Voxeo VoiceXML platforms, keep in mind that the maximum allowable xml grammar filesize will be right around 1 megabyte, although we do not recommend making a grammar of a size over 0.5 MB, as anything larger is when we start to see performance issues.

XML Comments

Since we are dealing with an XML construct rather than a GSL construct, we can use the same syntax for adding inline comments to our XML grammars as we do for our XML documents:


<?xml version= "1.0"?> 
<grammar xmlns="http://www.w3.org/2001/06/grammar" 
      xml:lang="en-US" root = "MYRULE"> 

  <rule id="MYRULE" scope="public"> 
    <one-of> 
<!-- In case you forgot, James Brown is the answer to everything -->
      <item>james brown </item> 
    </one-of> 
  </rule> 
</grammar>

More References

Oh, I see how it is, you want more information, do you? Look no further. The Nuance Grammar Guide contains all kinds of additional info that can help you out when you want more details on GSL, XML grammars, and the super-cool 'x-nuance' SLM grammars. Check it out today, and enlighten thyself!

Download the Code!

Prophecy source code

ANNOTATIONS: EXISTING POSTS

hstclair

8/7/2006 2:25 PM (EDT)

Your example here (and another that I've seen but can't recall where) uses an attribute called lang-list. I've run a quick search of the Nuance grammar guide of the W3C Speech Recognition Grammar documents and cannot find it defined anywhere. Is this simply a typo?

Incidentally, your documentation and examples are great.

Thanks

MattHenry

8/7/2006 8:41 PM (EDT)

Hello there,

Thanks for the kind words about the docs. The 'lang-list' instances were being carried over from an older docset where this attribute was required in order form SRGS grammars to function properly, and this is no longer relevant to the platform. I have removed instances of this attribute from our internal docset, which should be pushed out live in the next week or two.

Thanks for catching that for us!

~Matthew Henry

hstclair

8/28/2006 12:05 PM (EDT)

One more note that might be of help to someone else.

It is possible to embed a quotation mark into the return string within Nuance's Grammar language by simply including a double quote.

Specifically:

assign(myVariable "my string with ""quotation marks"" embedded within it")

or

return("<MyXml attribute=""something"" />")

This does not appear to be documented anywhere (although I cannot guarantee that my search was exhaustive).

draftbeer80

12/7/2006 6:51 AM (EST)

I studied both GSL and grxml. And I know this might sound like it's a stupid question but which one is better? GSL or grxml? Performance-wise or judging by the ease-of-use. I thought that GSL is easier to use and easier to understand. However, I am afraid to create my grammar in GSL because I am inexperienced and I don't wanna start developing a huge grammar and then find out later that it would have been better if I did it in grxml. I wanna find out if there are advantages in developing a grammar using grxml, as well as disadvantages. And the same with GSL. I hope you guys would humor this newbie's "ignorance". heheheh. Thanks!

VoxeoTony

12/7/2006 4:37 PM (EST)

You pose a very good question. You are asking which grammar is better based on performance and ease of use as guidelines. To start with GSL has been around for some time and is a well documented format with many pre-built samples that may be handy in the case where a plug-in is needed. We have some sample grammars on our site as well. This makes it easy to get operational quickly.

grXML has it's benefits regarding the facts that it's a W3C XML standard, where GSL is proprietary Nuance format. This means that grXML may be the direction to go if the developer is thinking long term development. The caveat is that not as many samples are available for quick setup and plug-in to applications.

I'm going to point you to our grammar tutorial for more information that may help you with your decision process. http://docs.voxeo.com/voicexml/2.0/t_21.htm?search=grammar#anchor

When you have chosen, let us know so we can see the path you've picked out for yourself.

Regards,

Tony

draftbeer80

12/7/2006 9:18 PM (EST)

Ok thanks Tony for your reply. Well, now that you've mentioned "longterm" then I guess I'm sticking with grxml. Can you perhaps suggest a good link to grxml tutorials? I know it was mentioned in the link you gave me but I would know more of the grxml equivalent of GSL grammar operators (disjunction operator, concatenation, optional etc.).

:-D
Chris

VoxeoTony

12/7/2006 11:23 PM (EST)

Hi Chris,

At this time the grXML documentaion on our site is being worked and more info getting ready to post. This is the link to the W3C grammar bible so to speak. http://www.w3.org/TR/speech-grammar/

The goal of Voxeo is to have our browser work with the W3C specification, so this link should get you the basics and more.

Hope this helps.

Regards,

Tony

draftbeer80

12/8/2006 2:00 AM (EST)

Ok, thanks so much Tony for the link you gave me. That would be of big help.

Merci beaucoup!
Chris

suma.gowda

6/6/2008 5:08 AM (EDT)

<?xml version= "1.0"?>
<grammar xmlns="http://www.w3.org/2001/06/grammar"
xml:lang="en-US" root = "MYRULE">

<rule id="MYRULE" scope="public">
<one-of>
<item>james brown </item>
</one-of>
</rule>
</grammar>
In the above example, can you please explain why root="MYRULE" and rule id="MYRULE" both are same??????

can they be different and why????????

voxeojeremyr

6/6/2008 6:28 AM (EDT)

Hi Suma,

I have posted this response as well in your forum posting but also wanted to put it here, so that if anyone else has the same question, they can see it here.

In the <grammar> element, the attribute 'root' is used to define the root rule that this grammar uses. In the <rule> element the id attribute is the name for this particular rule. Consider for instance this grammar:

<grammar mode="DTMF" root="App_name">
<rule id="App_name" scope="public">
<one-of>
<item>1</item>
</one-of>
</rule>
<rule id="Number2Rule" scope="public">
<one-of>
<item>2</item>
</one-of>
</rule>
</grammar>

If I wanted to call the Number2Rule from VXML, I would use the following syntax:
<grammar src="grammarfile.xml#Number2Rule ...>

This would invoke only the 'Number2Rule' for this particular utterance.

Thanks,
Jeremy Richmond
Voxeo Support

LetsAsk

10/7/2008 3:49 AM (EDT)

Hello all,

I tried to use XML grammar with my sample application of recognizing dtmf. But whenever I enter pin (5 digits followed by pound key), it gives me <nomatch> message all the time. Please let me know where I went wrong.

I attach my sample code for your reference.
**************************
<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">

<form id="Pincode">

<field name="pindtmf" slot="pindtmf">
<prompt timeout="8s">
Please key in pin followed by pound key.
</prompt>

<grammar mode="dtmf" version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.w3.org/2001/06/grammar
http://www.w3.org/TR/speech-grammar/grammar.xsd"
xmlns="http://www.w3.org/2001/06/grammar">
<rule id="digit">
<one-of>
<item> 1 </item>
<item> 2 </item>
<item> 3 </item>
<item> 4 </item>
<item> 5 </item>
<item> 6 </item>
<item> 7 </item>
<item> 8 </item>
<item> 9 </item>
</one-of>
</rule>
<rule id="pin" scope="public">
<one-of>
<item>
<item repeat="5"><ruleref uri="#digit"/></item>
#
</item>
</one-of>
</rule>
</grammar>
<noinput>
<prompt>
You did not enter anything. Please try again.
</prompt>
<reprompt/>
</noinput>
<nomatch>
<prompt>
I could not recognize that choice. Please try again.
</prompt>
<reprompt/>
</nomatch>
</field>
<filled namelist="pindtmf" mode="all">
<prompt>Did you enter <value expr="pindtmf"/>?</prompt>
</filled>
</form>
</vxml>

**************************

Thanks...

voxeoJeffK

10/7/2008 4:54 AM (EDT)

Hi,

There are a few things incorrect. If you don't declare the root rule then it is assumed the first rule is the root. In this case you have the "digit" rule first whereas your "pin" is the desired root. It is probably best to adhere to both practices.

Next, you have not set a scope on the "digit" rule. This defaults it to private, so the "pin" rule is not able to access it. Let's scope it as public.

Next is the '#' character. The '#' is already the default termchar unless you have changed it with the <property> tag. Also, since you are restricting digit input to 5 here:
<item repeat="5"><ruleref uri="#digit"/></item>
then the match will fire as soon as the fifth digit is hit, so the user will not be able to hit the '#' anyway! To give you control over that I changed the termchar at the top of the script.

I have made the changes for you. Please do not hesitate to ask if we can clarify anything, or if you have further question.

regards,
Jeff K.

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">


<property name="termchar" value="*"/>
<form id="Pincode">

<field name="pindtmf" slot="pindtmf">
<prompt timeout="8s">
Please key in pin followed by pound key.
</prompt>

<grammar mode="dtmf" version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.w3.org/2001/06/grammar
http://www.w3.org/TR/speech-grammar/grammar.xsd"
xmlns="http://www.w3.org/2001/06/grammar">

<rule id="pin" scope="public">
<item repeat="5"><ruleref uri="#digit"/></item>
<item> # </item>
</rule>

<rule id="digit" scope="public">
<one-of>
<item> 1 </item>
<item> 2 </item>
<item> 3 </item>
<item> 4 </item>
<item> 5 </item>
<item> 6 </item>
<item> 7 </item>
<item> 8 </item>
<item> 9 </item>
</one-of>
</rule>

</grammar>

<noinput>
<prompt>
You did not enter anything. Please try again.
</prompt>
<reprompt/>
</noinput>
<nomatch>
<prompt>
I could not recognize that choice. Please try again.
</prompt>
<reprompt/>
</nomatch>
</field>
<filled namelist="pindtmf" mode="all">
<prompt>Did you enter <value expr="pindtmf"/>?</prompt>
</filled>
</form>
</vxml>

LetsAsk

10/7/2008 6:30 AM (EDT)

Thanks a lot Jeff.

It works for me.
I had copied code from http://www.w3.org/TR/speech-grammar/#AppE
So, probably they should be blamed for all these troubles. :-)

J: grXML Grammars

| TOC

| grXML Hints