rule Element

  • Article
  Microsoft Speech Technologies Homepage

Defines a grammar rule. The rule element associates a valid rule expansion with a rulename, and sets the scope of the rule definition. Rule elements contain text or other XML elements that specify what speakers can say, and the order in which they can say it. A valid rule element must contain at least one piece of recognizable text or one rule reference.

The rulename for each rule must be unique within the grammar that contains the rule. The value of the rule element's id attribute specifies the rulename.

The rule element is required to make a valid grammar.

<rule
   id = string
   scope = (public | private) 
   sapi:dynamic = (true | false) >
</rule>

Attributes

  • id
    Required. Specifies the rulename that identifies the rule. The rulename must be unique within the containing grammar, or rule namespace. The same rulename can be used in multiple grammars. The rulename is a case-insensitive character sequence that:

    • Is a valid XML name
    • Does not contain the ".", ":", or "-" characters
    • Is not the name of a special rule (NULL, "VOID," or "GARBAGE")

    Note  The Speech API (SAPI) handles grammar rule id values as case-insensitive parameters. For example, SAPI will handle rules with the id values "Rule1" and "RULE1" as if they are identical rules. Do not rely on character casing in id attribute value strings to distinguish different rules.

  • scope
    Optional. Specifies whether the rule can be used only within its containing grammar or if it can be referenced by another grammar. The scope of a rule differs from the scope of the containing grammar. The scope of the containing grammar indicates where in an application the grammar is active. If specified, this attribute must have one of the following values.

    • private: The rule is visible only within its containing grammar. A private rule can be referenced by an external grammar if the rule is declared as the root rule of its containing grammar.
    • public: The rule can be referenced by an external grammar (in a ruleref element in the grammar making the reference). A public rule can always be activated for recognition.

    If omitted, the default value is "private."

  • sapi:dynamic
    Optional. Specifies whether the rule can be modified dynamically. Value is either true or false. If specified, the containing grammar element must have the following attribute-value pair:

    xmlns:sapi="https://schemas.microsoft.com/Speech/2002/06/SRGSExtensions"

Remarks

A rule can be identified as the root rule of the grammar that contains it, using the root attribute on the grammar element. The root rule is the default rule used by a ruleref element when that reference specifies only that a specific grammar, and not a specific rulename within that grammar, is referenced.

The rule element is used to define inline grammars. A rule element cannot be directly empty or contain only white space; however, it can contain empty elements, thus making it empty in grammar logic.

Examples

Example 1

The following example demonstrates that the publicRule rule can be referenced by a rule contained in an external grammar.

<grammar version="1.0" xmlns="http://www.w3.org/2001/06/grammar"
 xml:lang="en-US" tag-format="semantics-ms/1.0" ...>
   <rule id="publicRule" scope="public"> ... </rule>
</grammar>

Example 2

The following example demonstrates private rules. The referenceYes rule can be referenced by an external grammar. The referenceNo rule cannot be referenced by an external grammar.

<!-- The "referenceNo" rule cannot be referenced by an external grammar. -->
<!-- Although the "referenceYes" rule is scoped as private, it can be referenced -->
<!-- by an external grammar because it is the root rule of its containing grammar. -->

   <grammar root="referenceYes" version="1.0" xmlns="http://www.w3.org/2001/06/grammar"
 xml:lang="en-US" tag-format="semantics-ms/1.0" ...>
      <rule id="referenceNo" scope="private"> ... </rule>
      <rule id="referenceYes" scope="private"> ... </rule>
   </grammar>

Example 3

The following example demonstrates how to reference rules using ruleref elements. The first ruleref element in the customerInfo.grxml grammar leads to the food rule in the restaurantInfo.grxml grammar, even though the food rule is scoped as private, because the food rule is identified as the root rule of the restaurantInfo.grxml grammar.

<!-- Grammar file "customerInfo.grxml" -->
      <grammar version="1.0" xmlns="http://www.w3.org/2001/06/grammar"
 xml:lang="en-US" tag-format="semantics-ms/1.0" ... >
         <rule id="customers">    
            <item repeat="0-1">I would like</item>
            <ruleref uri="restaurantInfo.grxml"/>
            <item repeat="0-1">in</item>
            <ruleref uri="restaurantInfo.grxml#location"/>
         </rule>
      </grammar>

<!-- Grammar file "restaurantInfo.grxml" -->
   <grammar root="food" version="1.0" xmlns="http://www.w3.org/2001/06/grammar"
 xml:lang="en-US" tag-format="semantics-ms/1.0" ... >
      <rule id="food" scope="private">
            <one-of>
               <item>italian</item>
               <item>thai</item>
            </one-of>
      </rule>
      <rule id="location" scope="public"> 
            <one-of>
               <item>Bellevue</item>
               <item>Redmond</item>
               <item>Seattle</item>
            </one-of> 
      </rule>
   </grammar>

See Also

Grammar XML