# Grammar definition
<a name="grammar-srgs-spec"></a>

This topic shows the parts of the SRGS specification that Amazon Lex V2 supports. All of the rules are defined in the SRGS specification. For more information, see the [ Speech recognition grammar specification version 1.0](https://www.w3.org/TR/speech-grammar/) W3C recommendation.

**Topics**
+ [Header declarations](srgs-header.md)
+ [Supported XML elements](srgs-supported-xml.md)
+ [Tokens](srgs-tokens.md)
+ [Rule reference](srgs-rule-reference.md)
+ [Sequences and encapsulation](srgs-sequence.md)
+ [Repeats](srgs-repeats.md)
+ [Language](srgs-language.md)
+ [Tags](srgs-tags.md)
+ [Weights](grammar-weights.md)

This document includes material copied and derived from the W3C Speech Recognition Grammar Specification Version 1.0 (available at [https://www.w3.org/TR/speech-grammar/](https://www.w3.org/TR/speech-grammar/)). Citation information follows:

[Copyright](http://www.w3.org/Consortium/Legal/ipr-notice#Copyright) © 2004 [W3C®](http://www.w3.org/) ([MIT](http://www.csail.mit.edu/), [ERCIM](http://www.ercim.org/), [Keio](http://www.keio.ac.jp/), All Rights Reserved. W3C [liability](http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer), [trademark](http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks), [document use](http://www.w3.org/Consortium/Legal/copyright-documents) and [software licensing](http://www.w3.org/Consortium/Legal/copyright-software) rules apply.

The SRGS specification document, a [W3C Recommendation](https://www.w3.org/2004/02/Process-20040205/tr.html#RecsW3C), is available from the W3C under the following license.

## License text
<a name="license-text"></a>

License

By using and/or copying this document, or the W3C document from which this statement is linked, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:

Permission to copy, and distribute the contents of this document, or the W3C document from which this statement is linked, in any medium for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the document, or portions thereof, that you use:
+ A link or URL to the original W3C document.
+ The pre-existing copyright notice of the original author, or if it doesn't exist, a notice (hypertext is preferred, but a textual representation is permitted) of the form: "Copyright © [\$1date-of-document] [World Wide Web Consortium](http://www.w3.org/), ([MIT](http://www.csail.mit.edu/), [ERCIM](http://www.ercim.org/), [Keio](http://www.keio.ac.jp/), [Beihang](http://ev.buaa.edu.cn/)). [http://www.w3.org/Consortium/Legal/2015/doc-license](http://www.w3.org/Consortium/Legal/2015/doc-license)"
+ *If it exists*, the STATUS of the W3C document.

When space permits, inclusion of the full text of this **NOTICE** should be provided. We request that authorship attribution be provided in any software, documents, or other items or products that you create pursuant to the implementation of the contents of this document, or any portion thereof.

No right to create modifications or derivatives of W3C documents is granted pursuant to this license, except as follows: To facilitate implementation of the technical specifications set forth in this document, anyone may prepare and distribute derivative works and portions of this document in software, in supporting materials accompanying software, and in documentation of software, PROVIDED that all such works include the notice below. HOWEVER, the publication of derivative works of this document for use as a technical specification is expressly prohibited.

In addition, "Code Components" —Web IDL in sections clearly marked as Web IDL; and W3C-defined markup (HTML, CSS, and so on) and computer programming language code clearly marked as code examples— are licensed under the [W3C Software License](http://www.w3.org/Consortium/Legal/copyright-software).

The notice is:

"Copyright © 2015 W3C® (MIT, ERCIM, Keio, Beihang). This software or document includes material copied from or derived from [title and URI of the W3C document]."

Disclaimers

THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.

# Header declarations
<a name="srgs-header"></a>

The following table shows the header declarations supported by the grammar slot type. For more information, see [ Grammar header declarations ](https://www.w3.org/TR/speech-grammar/#S4.1) in the *Speech recognition grammar specification version 1* W3C recommendation.


| Declaration | Specification requirement | XML form | Amazon Lex support | Specification | 
| --- | --- | --- | --- | --- | 
| Grammar version | Required | [4.3](https://www.w3.org/TR/speech-grammar/#S4.3): version attribute on grammar element | Required | SRGS | 
| XML namespace | Required (XML only) | [4.3](https://www.w3.org/TR/speech-grammar/#S4.3): xmlns attribute on grammar element | Required | SRGS | 
| Document type | Required (XML only) | [4.3](https://www.w3.org/TR/speech-grammar/#S4.3): XML DOCTYPE | Recommended | SRGS | 
| Character encoding | Recommended | [4.4](https://www.w3.org/TR/speech-grammar/#S4.4): encoding attribute in XML declaration | Recommended | SRGS | 
| Language | Required in voice mode Ignored in DTMF mode | [4.5](https://www.w3.org/TR/speech-grammar/#S4.5): xml:lang attribute on grammar element | Required in voice mode Ignored in DTMF mode | SRGS | 
| Mode | Optional | [4.6](https://www.w3.org/TR/speech-grammar/#S4.6): mode attribute on grammar element | Optional | SRGS | 
| Root rule | Optional | [4.7](https://www.w3.org/TR/speech-grammar/#S4.7): root attribute on grammar element | Required | SRGS | 
| Tag format | Optional | [4.8](https://www.w3.org/TR/speech-grammar/#S4.8): tag-format attribute on grammar element | String literal and ECMAScript are supported | SRGS, SISR | 
| Base URI | Optional | [4.9](https://www.w3.org/TR/speech-grammar/#S4.9): xml:base attribute on grammar element | Optional | SRGS | 
| Pronunciation lexicon | Optional, multiple allowed | [4.10](https://www.w3.org/TR/speech-grammar/#S4.`0): lexicon element | Not supported | SRGS, PLS | 
| Metadata | Optional, multiple allowed | [4.11.1](https://www.w3.org/TR/speech-grammar/#S4.11.1): meta element | Required | SRGS | 
| XML metadata | Optional, XML only | [4.11.2](https://www.w3.org/TR/speech-grammar/#S4.11.2): metadata element | Optional | SRGS | 
| Tag | Optional, multiple allowed | [4.12](https://www.w3.org/TR/speech-grammar/#S4.12): tag element | Global tags not supported | SRGS | 

**Example**

```
<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE grammar PUBLIC "-//W3C//DTD GRAMMAR 1.0//EN"
                  "http://www.w3.org/TR/speech-grammar/grammar.dtd">

<grammar xmlns="http://www.w3.org/2001/06/grammar"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xml:base="http://www.example.com/base-file-path"
         xsi:schemaLocation="http://www.w3.org/2001/06/grammar
                             http://www.w3.org/TR/speech-grammar/grammar.xsd"
         xml:lang="en-US"
         version="1.0"
         mode="voice"
         root="city"
         tag-format="semantics/1.0">
```

# Supported XML elements
<a name="srgs-supported-xml"></a>

Amazon Lex V2 supports the following XML elements for custom grammars:
+ `<item>`
+ `<token>`
+ `<tag>`
+ `<one-of>`
+ `<rule-ref>`

# Tokens
<a name="srgs-tokens"></a>

The following table shows the token specifications supported by the grammar slot type. For more information, see [ Tokens ](https://www.w3.org/TR/speech-grammar/#S2.1) in the *Speech recognition grammar specification version 1* W3C recommendation.


| Token type | Example | Supported? | 
| --- | --- | --- | 
| Single unquoted token | hello | Yes | 
| Single unquoted token: non-alphabetic | 2 | Yes | 
| Single quoted token, no white space | "hello" | Yes, drop double quotes when it only contains a single token | 
| Two tokens delimited by white space | bon voyage | Yes | 
| Four tokens delimited by white space | this is a test | Yes | 
| Single quoted token, including white space | "San Francisco | No | 
| Single XML token in <token> tag | <token>San Francisco</token> | No (same as single quoted token with white space) | 

**Notes**
+ *Single quoted token including white space* – The specification requires words enclosed in double quotes be treated as a single token. Amazon Lex V2 treats them as white space delimited tokens.
+ *Single XML token in <token>* – The specification requires words delimited by <token> to represent one token. Amazon Lex V2 treats them as white space delimited tokens.
+ Amazon Lex V2 throws a validation error when either usage is found in your grammar.

**Example**

```
<rule id="state" scope="public">
    <one-of>
        <item>FL</item>
        <item>MA</item>
        <item>NY</item>
    </one-of>
</rule>
```

# Rule reference
<a name="srgs-rule-reference"></a>

The following table summarizes the various forms of rule reference that are possible within grammar documents. For more information, see [ Rule reference ](https://www.w3.org/TR/speech-grammar/#S2.2) in the *Speech recognition grammar specification version 1* W3C recommendation. 


| Reference type | XML form | Supported | 
| --- | --- | --- | 
| [ 2.2.1 ](https://www.w3.org/TR/speech-grammar/#S2.2.1) Explicit local rule reference | <ruleref uri="\$1rulename"/> | Yes | 
| [ 2.2.2 ](https://www.w3.org/TR/speech-grammar/#S2.2.2) Explicit reference to a named rule of a grammar identified by a [URI](https://www.w3.org/TR/speech-grammar/#term-uri) | <ruleref uri="grammarURI\$1rulename"/> | No | 
| [ 2.2.2 ](https://www.w3.org/TR/speech-grammar/#S2.2.2) Implicit reference to the root rule of a grammar identified by a [URI](https://www.w3.org/TR/speech-grammar/#term-uri) | <ruleref uri="grammarURI"/> | No | 
| [ 2.2.2 ](https://www.w3.org/TR/speech-grammar/#S2.2.2) Explicit reference to a named rule of a grammar identified by a [URI](https://www.w3.org/TR/speech-grammar/#term-uri) with a [media type](https://www.w3.org/TR/speech-grammar/#term-media-type) | <ruleref uri="grammarURI\$1rulename" type="media-type"/> | No | 
| [ 2.2.2 ](https://www.w3.org/TR/speech-grammar/#S2.2.2) Implicit reference to the root rule of a grammar identified by a [URI](https://www.w3.org/TR/speech-grammar/#term-uri) with a [media type](https://www.w3.org/TR/speech-grammar/#term-media-type) | <ruleref uri="grammarURI" type="media-type"/> | No | 
| [ 2.2.3 ](https://www.w3.org/TR/speech-grammar/#S2.2.3) Special rule definitions | `<ruleref special="NULL"/>` `<ruleref special="VOID"/>` `<ruleref special="GARBAGE"/>` | No | 

**Notes**

1. Grammar URI is an external URI. For example, `http://grammar.example.com/world-cities.grxml`.

1. Media type can be:
   + `application/srgs+xml`
   + `text/plain`

**Example**

```
<rule id="city" scope="public">
    <one-of>
        <item>Boston</item>
        <item>Philadelphia</item>
        <item>Fargo</item>
    </one-of>
</rule>

<rule id="state" scope="public">
    <one-of>
        <item>FL</item>
        <item>MA</item>
        <item>NY</item>
    </one-of>
</rule>

<!-- "Boston MA" -> city = Boston, state = MA -->
<rule id="city_state" scope="public">
    <ruleref uri="#city"/> <ruleref uri="#state"/>
</rule>
```

# Sequences and encapsulation
<a name="srgs-sequence"></a>

The following example shows the supported sequences. For more information, see [Sequences and encapsulation](https://www.w3.org/TR/speech-grammar/#S2.3) in the *Speech recognition grammar specification version 1* W3C recommendation. 

**Example**

```
<!-- sequence of tokens -->
this is a test

<!--sequence of rule references-->
<ruleref uri="#action"/> <ruleref uri="#object"/>

<!--sequence of tokens and rule references-->
the <ruleref uri="#object"/> is <ruleref uri="#color"/>

<!-- sequence container -->
<item>fly to <ruleref uri="#city"/> </item>
```

# Repeats
<a name="srgs-repeats"></a>

The following table shows the supported repeated expansions for rules. For more information, see [Repeats](https://www.w3.org/TR/speech-grammar/#S2.5) in the *Speech recognition grammar specification version 1* W3C recommendation. 


| XML formExample | Behavior | Supported? | 
| --- | --- | --- | 
| *repeat="n"* repeat="6" | The contained expression is repeated exactly "n" times. "n" must be "0" or a positive integer. | Yes | 
| *repeat="m-n"* repeat="4-6" | The contained expansion is repeated between "m" and "n" times (inclusive). "m" and "n" must both be "0" or a positive integer, and "m" must be less than or equal to "n". | Yes | 
| *repeat="m-"* repeat="3-" | The contained expansion is repeated "m" times or more (inclusive). "m" must be "0" or a postive integer. For example, "3-" declares that the contained expansion can occur three, four, five, or more times. | Yes | 
| *repeat="0-1"*  | The contained expansion is optional. | Yes | 
| <item repeat="2-4" repeat-prob="0.8"> |   | No | 

# Language
<a name="srgs-language"></a>

The following discussion applies to language identifiers applied to grammars. For more information, see [Language](https://www.w3.org/TR/speech-grammar/#S2.7) in the *Speech recognition grammar specification version 1* W3C recommendation. 

By default a grammar is a single language document with a [language identifier](https://www.w3.org/TR/speech-grammar/#term-language) provided in the language declaration in the [grammar header](https://www.w3.org/TR/speech-grammar/#S4.1). All tokens within that grammar, unless otherwise declared, **will be handled according to the grammar's language**. Grammar-level language declarations **are not supported**.

In the following example:

1. The grammar header declaration for the language "en-US" **is supported** by Amazon Lex V2.

1. Item-level language attachment (highlighted in *red*) **is not supported**. Amazon Lex V2 throws a validation error if a language attachment is different from the header declaration.

```
<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE grammar PUBLIC "-//W3C//DTD GRAMMAR 1.0//EN"
                  "http://www.w3.org/TR/speech-grammar/grammar.dtd">

<!-- the default grammar language is US English -->
<grammar xmlns="http://www.w3.org/2001/06/grammar"
         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"
         xml:lang="en-US" version="1.0">

  <!--
     single language attachment to tokens
     "yes" inherits US English language
     "oui" is Canadian French language
  -->
  <rule id="yes">
    <one-of>
      <item>yes</item>
      <item xml:lang="fr-CA">oui</item>
    </one-of>
  </rule>

  <!-- Single language attachment to an expansion -->
  <rule id="people1">
    <one-of xml:lang="fr-CA">
      <item>Michel Tremblay</item>
      <item>André Roy</item>
    </one-of>
  </rule>
</grammar>
```

# Tags
<a name="srgs-tags"></a>

The following discussion applies to tags defined for grammars. For more information, see [Tags](https://www.w3.org/TR/speech-grammar/#S2.6) in the *Speech recognition grammar specification version 1* W3C recommendation. 

Based on the SRGS specification, tags can be defined in the following ways:

1. As part of a header declaration as described in [Header declarations](srgs-header.md).

1. As part of a *<rule>* definition.

The following tag formats are supported:
+ `semantics/1.0` (SISR, ECMAScript)
+ `semantics/1.0-literals` (SISR string literals)

The following tag formats are not supported:
+ `swi-semantics/1.0` (Nuance proprietary)

**Example**

```
<grammar xmlns="http://www.w3.org/2001/06/grammar"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xml:base="http://www.example.com/base-file-path"
         xsi:schemaLocation="http://www.w3.org/2001/06/grammar
                             http://www.w3.org/TR/speech-grammar/grammar.xsd"
         xml:lang="en-US"
         version="1.0"
         mode="voice"
         root="city"
         tag-format="semantics/1.0-literals">
    <rule id="no">
        <one-of>
            <item>no</item>
            <item>nope</item>
            <item>no way</item>
        </one-of>
        <tag>no</tag>
    </rule>
</grammar>
```

# Weights
<a name="grammar-weights"></a>

You can add the *weight* attribute to an element. Weight is a positive floating point value that represents the degree to which the phrase in the item is boosted during speech recognition. For more information, see [Weights](https://www.w3.org/TR/speech-grammar/) in the Speech recognition grammar specification version 1 W3C recommendation.

Weights must be greater than 0 and less than or equal to 10, and can have only one decimal place. If the weight is greater than 0 and less than 1, the phrase is negatively boosted. If the weight is greater than 1 and less than or equal to 10, the phrase is positively boosted. A weight of 1 is equivalent to giving no weight at all, and there is no boosting for the phrase.

Assigning appropriate weights to items for improving speech recognition performance is a difficult task. Here are some tips you can follow for assigning weights:
+ Start with a grammar without item weights assigned.
+ Determine which patterns in the speech are frequently misidentified.
+ Apply different values for weights until you notice an improvement in the speech recognition performance, and there are no regressions.

**Example 1**

For example, if you have a grammar for airports, and you observe that *New York* is frequently misidentified as *Newark*, you can positively boost New York by assigning it a weight of 5.

```
<rule> id="airport">
    <one-of>
        <item>
            Boston
            <tag>out="Boston"</tag>
        </item>
        <item weight="5">
            New York
            <tag>out="New York"</tag>
        </item>
        <item>
            Newark
            <tag>out="Newark"</tag>
        </item>
    </one-of>
</rule>
```

**Example 2**

For example, you have a grammar for the airline reservation code starting with an English alphabet followed by three digits. The reservation code most likely starts with B or D, but you observe that B is frequently misidentified as P, and D as T. You can positively boost B and D.

```
<rule> id="alphabet">
    <one-of>
        <item>A<tag>out.letters+='A';</tag></item>
        <item weight="3.5">B<tag>out.letters+='B';</tag></item>
        <item>C<tag>out.letters+='C';</tag></item>
        <item weight="2.9">D<tag>out.letters+='D';</tag></item>
        <item>E<tag>out.letters+='E';</tag></item>
        <item>F<tag>out.letters+='F';</tag></item>
        <item>G<tag>out.letters+='G';</tag></item>
        <item>H<tag>out.letters+='H';</tag></item>
        <item>I<tag>out.letters+='I';</tag></item>
        <item>J<tag>out.letters+='J';</tag></item>
        <item>K<tag>out.letters+='K';</tag></item>
        <item>L<tag>out.letters+='L';</tag></item>
        <item>M<tag>out.letters+='M';</tag></item>
        <item>N<tag>out.letters+='N';</tag></item>
        <item>O<tag>out.letters+='O';</tag></item>
        <item>P<tag>out.letters+='P';</tag></item>
        <item>Q<tag>out.letters+='Q';</tag></item>
        <item>R<tag>out.letters+='R';</tag></item>
        <item>S<tag>out.letters+='S';</tag></item>
        <item>T<tag>out.letters+='T';</tag></item>
        <item>U<tag>out.letters+='U';</tag></item>
        <item>V<tag>out.letters+='V';</tag></item>
        <item>W<tag>out.letters+='W';</tag></item>
        <item>X<tag>out.letters+='X';</tag></item>
        <item>Y<tag>out.letters+='Y';</tag></item>
        <item>Z<tag>out.letters+='Z';</tag></item>
    </one-of>
</rule>
```