rule Element

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Defines a grammar rule. The rule element associates a valid rule expansion with a rule name 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 name for each rule must be unique within the grammar that contains the rule. The value of the rule element's id attribute specifies the rule name.

The rule element is required to make a valid grammar.

Syntax

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

Attributes

Attribute	Definition
id	Required. Specifies the name that identifies the rule. The rule name must be unique within the containing grammar or rule namespace. The same rule name can be used in multiple grammars. The rule name is a case-sensitive character sequence that is a valid XML name, does not contain the ".", ":", or "-" characters, and 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 handles 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 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. Values are true or false. If specified, the containing grammar element must have the following attribute-value pair: xmlns:sapi="http://schemas.microsoft.com/Speech/2002/06/SRGSExtensions"

Remarks

A rule can be identified as the root rule of the grammar that contains it by 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 rule name 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 publicRulerule 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 referenceNorule 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 foodrule in the RestaurantInfo.grxml grammar, even though the foodrule is scoped as private, because the foodrule 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

Concepts

Grammar XML