Using the <tag> Element

Script expressions that are contained in tag elements generate semantic values for items and referenced rules that are contained in a containing rule element. These item-specific values can be associated with the Rule Variable of the containing rule as properties of that Rule Variable. Rule Variable Referencing provides more information on the various forms of reference to Rule Variables.

Placement of the <tag> Element

Author-defined scripts for generating semantic values must be contained inside tag elements:

<tag>$.property={}; $.property._value="desired value"; </tag>

Place tag elements so that they immediately follow the word or phrase for which a semantic value is needed, or immediately follow a ruleref that has a Rule Variable that contains information that the script expression is required to read.

Typically, words or phrases that require a semantic value are contained inside an item element. In this case, the tag element is contained within the item element. In World Wide Web Consortium (W3C) grammars, it is possible to include words or phrases in a grammar that are not explicitly contained in an item element, but that are nevertheless treated the same as words or phrases that are contained in an item element. In both of these cases, the script expression that is contained in the tag element is executed when the speech recognizer follows a path through the grammar that includes the words or phrases that the tag element follows.

A tag element can also be placed following a ruleref element. In this case, the script expression that is contained in the tag element is executed after the speech recognizer follows a path through the grammar that leads through the ruleref element. Use a tag element in this position to process the semantic information that is contained in the Rule Variable of the rule that the ruleref element references.

Values that are generated by scripts are attached to the Rule Variable of the rule that contains the tag element. The value corresponding to the root rule in the grammar is converted into the Semantic Markup Language (SML) output. Script expressions contained in semantic interpretation tags follow the syntax of ECMA-327.

Special Rule Variable Properties for Scripting

Every Rule Variable is predefined as an object and every Rule Variable has two predefined properties. Developers can use these properties with Rule Variables to more precisely control how the semantic interpreter serializes the semantic information that is produced by script expressions into Semantic Markup Language (SML) output. These properties are the _value and the _attributes property. The _value property produces the text content of a node, and the _attributes property produces XML attributes in the start tag of a node.

The predefined properties _value and _attributes do not create child nodes in the SML output. However, developer-defined properties of a Rule Variable create child nodes in the SML output. Since developer-defined properties create child nodes, the _value and _attributes properties can be used to set the text content and attributes of these child nodes as well. Examples using the _value property appear in this document. For more examples, refer to Semantic Markup Reference.

Examples of <tag> Element Placement and SML Results

The following examples illustrate tag element placement within grammar rules. The examples also illustrate the SML output for the rules provided.

In the following grammar, a tag element is placed within an item element in order to explicitly associate the expressions in the tag element with the content of the item element. The script expressions create a daynum property of the Rule Variable, and set the _value property of daynum to a numeric value. In the SML results, the daynum is a node, and the numeric value becomes the text content of the daynum node.

<rule id="WeekdaySelection">
  <one-of>
    <item>Monday<tag>$.daynum={}; $.daynum._value="1";</tag></item>
    <item>Wednesday<tag>$.daynum={}; $.daynum._value="3";</tag></item>
    <item>Friday<tag>$.daynum={}; $.daynum._value="5";</tag></item>
 </one-of>
</rule>

In response to the utterance, Monday, the speech recognizer selects a path through the item element containing "Monday." Following this path triggers the execution of the script that is contained by the tag element inside the item element containing "Monday." The script generates a property named daynum of the Rule Variable belonging to the WeekdaySelection rule, and associates the value 1 with daynum. This script produces the following SML output:

<SML confidence="0.850" text="Monday" utteranceConfidence="0.850">
  <daynum confidence="0.850">1</daynum>
</SML>

In the following grammar, a tag element follows a word that is not explicitly contained within an item element (the word "select"). Words or phrases in the grammar that are not explicitly contained in an item element are treated as if they were contained in an item element. The rule below recognizes the utterances select Monday, select Wednesday, and select Friday, and generates semantic values associated with both the word "select," and with the day name.

<rule id="WeekdaySelection">
  select<tag>$.specifier={}; $.specifier._value="on";</tag>
  <one-of>
    <item>Monday<tag>$.daynum={}; $.daynum._value="Day 1";</tag></item>
    <item>Wednesday<tag>$.daynum={}; $.daynum._value="Day 3";</tag></item>
    <item>Friday<tag>$.daynum={}; $.daynum._value="Day 5";</tag></item>
 </one-of>
</rule>

The spoken phrase, select Wednesday, generates a specifier and a daynum property of the Rule Variable WeekdaySelection, and associates the values on and Day 3 with these properties respectively, producing the following SML output:

<SML confidence="0.863" text="select Wednesday" utteranceConfidence="0.863">
  <specifier confidence="0.863">on</specifier>  
  <daynum confidence="0.863">Day 3</daynum>
</SML>

In the following grammar, the tag element immediately follows the ruleref element. This placement associates the script expressions that are contained in the tag element with the value returned by the ruleref element. This rule recognizes the utterances, Saturday morning, Saturday evening, Sunday morning, and Sunday evening, and generates numeric values representing the path that the recognizer follows through the grammar:

<rule id="AppointmentTime">
  <one-of>
    <item>Saturday<tag>$.daynum={}; $.daynum._value="6";</tag></item>
    <item>Sunday<tag>$.daynum={}; $.daynum._value="7";</tag></item>
  </one-of>
  <ruleref uri="#RelativeTime" /><tag>$.TimeRange=$RelativeTime;</tag>
</rule>

<rule id="RelativeTime">
  <one-of>
    <item>morning<tag>$.range={}; $.range._value="1";</tag></item>
    <item>evening<tag>$.range={}; $.range._value="2";</tag></item>
 </one-of>
</rule>

Notice the script that is contained in the tag element following the ruleref to RelativeTime. The script creates a property of the Rule Variable for AppointmentTime named TimeRange, and assigns the contents of the Rule Variable for RelativeTime to TimeRange.

The path followed in response to the utterance, Saturday morning, triggers the scripts associated with "Saturday," "morning," and with the ruleref to RelativeTime. This process generates the following data structure:

AppointmentTime => { daynum    =>   6            }
                   { TimeRange => { range => 1 } }

The semantic interpreter serializes the data structure into the following SML output:

<SML confidence="0.864" text="Saturday morning" utteranceConfidence="0.864">
    <daynum confidence="0.864">6</daynum>
    <TimeRange confidence="0.843">
        <range confidence="0.843">1</range>
    </TimeRange>
</SML>

Special Variables for Scripting

The Microsoft Speech Application SDK (SASDK) also provides a special variable named $recognized that is defined within the scope of every tag element. The $recognized variable has two attributes that enable developers to use recognition result information. These attributes and the value to which the recognizer automatically sets them are shown in the following table.

Attribute	Value
$recognized.text	Set to the recognition text for the rule element containing the script expression that uses the $recognized variable. Value is of type string.
$recognized.confidence	Set to the confidence score for the recognized text that is associated with the tag element containing the $recognized variable. Value is of type float, and is a floating-point number between 0.000 and 1.000.

The $recognized variable can be used only on the right side of expressions. The following grammar illustrates using the $recognized variable.

<grammar version="1.0" xmlns="http://www.w3.org/2001/06/grammar" 
 root="destination" xml:lang="en-US" tag-format="semantics-ms/1.0">

  <rule id="destination">
    <tag>$.varDemo={};</tag>
        Fly me to
        <one-of>
             <item>London</item>
             <item>Paris<tag>$._value="Arriving at Orly.";</tag></item>
             <item>Berlin</item>
      </one-of>
    <ruleref uri="#FlightDay" /><tag>$.varDemo.word=$$.rword; $.varDemo.score=$$.rscore;</tag>
  </rule>

  <rule id="FlightDay">
    on
    <one-of>
      <item>Monday</item>
      <item>Wednesday<tag>$.rword=$recognized.text; $.rscore=$recognized.confidence;</tag></item>
      <item>Friday</item>
    </one-of>
  </rule>

</grammar>

Using this grammar, the utterance, "Fly me to Paris on Wednesday," produces the following SML output:

<SML confidence="0.770" text="Fly me to Paris on Wednesday" utteranceConfidence="0.770">
  Arriving at Orly. 
  <varDemo confidence="0.770">
    <word>on Wednesday</word> 
    <score>0.849168</score> 
  </varDemo>
</SML>

Note  The word "recognized" is a reserved word and should not be used to identify rules (as the value of the id attribute of a rule element).