• Article

Note

Please see Azure Cognitive Services for Speech documentation for the latest supported speech solutions.

rule Element (Microsoft.Speech)

The rule element defines a grammar rule. A rule element contains text or XML elements that define what speakers can say, and the order in which they can say it. The rule element associates a valid rule definition with a rule name and sets the scope of the rule definition. A valid rule element must contain at least one piece of recognizable text or one rule reference. A valid grammar must contain at least one rule element.

Syntax

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

Attributes

Attribute

Description

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 characters ".", ":", or "-", and is not the name of a special rule (NULL, VOID, or GARBAGE).

scope

Optional. Specifies whether the rule can be used only within its containing grammar or referenced by another grammar. 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 (from 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="https://schemas.microsoft.com/Speech/2002/06/SRGSExtensions"

Important

Modifying an SRGS grammar dynamically in code requires the ISpGrammarBuilder interface, an API in the native code for the Speech Platform. You cannot dynamically modify an SRGS grammar using any of the Microsoft.Speech types.

Remarks

A rule element can contain unmarked text or any of the ruleref, item, one-of, token, or tag elements. A rule element cannot be empty or contain only white space; however, it can contain empty elements, thus making it empty in grammar logic.

A rule can be identified as the root rule of the grammar that contains it by using the root attribute on the grammar Element (Microsoft.Speech). The root rule is the default rule used by a ruleref Element (Microsoft.Speech) when that reference specifies only a grammar, and not a specific rule name within that grammar.

Examples

In the following example, the rule named publicRule can be referenced from a ruleref element in an external grammar, because its scope attribute is set to public.

<?xml version="1.0" encoding="utf-8"?>
<grammar version="1.0" xml:lang="en-US" mode="voice" root="publicRule"
 xmlns="http://www.w3.org/2001/06/grammar" tag-format="semantics/1.0">
  
  <rule id="publicRule" scope="public">
    <item> This content is accessible by an external grammar. </item>
  </rule>

</grammar>

The following example demonstrates private rules. Although the rule named referenceYes is scoped as private, it can be referenced by an external grammar because it is the root rule of its containing grammar. The rule named referenceNo cannot be referenced by an external grammar.

<?xml version="1.0" encoding="utf-8"?>
<grammar version="1.0" xml:lang="en-US" mode="voice" root="referenceYes"
 xmlns="http://www.w3.org/2001/06/grammar" tag-format="semantics/1.0">

  <rule id="referenceYes" scope="private">
    <one-of>
      <item> Yes </item>
      <item> Yep </item>
    </one-of>
  </rule>

  <rule id="referenceNo" scope="private"> 
    <one-of>
      <item> No </item>
      <item> Nope </item>
    </one-of>
  </rule>

</grammar>

The following example demonstrates how to reference a rule using a ruleref Element (Microsoft.Speech). The first ruleref element in the "CustomerInfo.grxml" grammar points to the rule named food in the grammar "RestaurantInfo.grxml". This is a valid rule reference even though the rule named food is scoped as private, because it is declared as the root rule of the "RestaurantInfo.grxml" grammar.

The second ruleref element in "CustomerInfo.grxml" references the public rule named location in "RestaurantInfo.grxml".

<!-- Grammar file "customerInfo.grxml" -->
<?xml version="1.0" encoding="utf-8"?>
<grammar version="1.0" xml:lang="en-US" mode="voice" root="customers"
 xmlns="http://www.w3.org/2001/06/grammar" tag-format="semantics/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" -->
<?xml version="1.0" encoding="utf-8"?>
<grammar version="1.0" xml:lang="en-US" mode="voice" root="food"
 xmlns="http://www.w3.org/2001/06/grammar" tag-format="semantics/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 Rules (Microsoft.Speech)