Dictionaries node

A list entity can have an associated dictionary. The dictionary is the list of spoken forms that correspond to entities or “mentions” that are part of the entity. For example, a City entity can have literals such as “New York City”, “New York”, and “The Big Apple”.

A dictionary entry always has a literal and can optionally have a value.

The literal represents the exact spoken text that is present within an utterance (what the user said). For example, in the query “I’d like a large t-shirt”, the literal corresponding to the entity [TSHIRT_SIZE] is “large”. Other literals might be “small”, “medium”, “big”, “very big”, and “extra large”. When you annotate samples, you select a range of text to tag with an entity.

The value corresponds to what is returned in the JSON NLU results whenever the input utterance has a matching literal for this entity, through a process called canonicalization. Values can be any string you want. For example, a CoffeeType entity could have the literals “coffee” and “americano”, and both literals would correspond to the value “americano”.

Dictionaries XML meta

<dictionaries>
  <dictionary conceptref="str">
    <entry literal="str" value="str"/>
  </dictionary>
</dictionaries>

Dictionaries node specification

The dictionaries node is defined as follows:

  • The dictionaries node contains zero-many dictionary nodes.
  • Each dictionary node contains zero-many entry nodes
  • Each dictionary node contains a required attribute conceptref, which defines the entity the entries apply to.

Each entry node has the following attributes:

Dictionary entry node attributes
Attribute Required? Description
literal Required Text that is present within an utterance. The literal is tokenized and normalized.
value Optional Value returned in the JSON NLU results.
protected Optional Used to identify data that is confidential and should not be exposed.
Default value is false. Do not set this field to true, otherwise you will not be able to access the data.
sourceref Optional Source of the entry. For example: DTV_Domain.

Dictionaries node example

The dictionaries consist of literal-value pairs that relate to a specific entity. This example showcases an entity “SEARCH_ENGINE”, which is defined as list type entity. The value is optional. The canonicalization of wikipedia and duck duck go showcase how to use the value attribute.

<dictionaries>
    <dictionary conceptref="SEARCH_ENGINE">
        <entry literal="bing" value="bing"/>
        <entry literal="duck duck go" value="duckduckgo"/>
        <entry literal="duckduckgo" value="duckduckgo"/>
        <entry literal="google" value="google"/>
        <entry literal="wiki" value="wikipedia"/>
        <entry literal="wikipedia" value="wikipedia"/>
        <entry literal="wikipédia" value="wikipedia"/>
        <entry literal="yahoo" value="yahoo"/>
    </dictionary>
</dictionaries>

Dictionaries schema

<xs:element name='dictionaries'>
    <xs:annotation>
        <xs:documentation>Dictionaries: Instances of list type Entities (static or dynamic type), that can have canonical values.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
        <xs:sequence>
            <xs:element minOccurs='0' maxOccurs='unbounded' ref='dictionary'/>
        </xs:sequence>
    </xs:complexType>
</xs:element>
<xs:element name='dictionary'>
    <xs:annotation>
        <xs:documentation>Entity Dictionary: Entity will have entries defining the entities.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
        <xs:sequence>
            <xs:element minOccurs='0' maxOccurs='unbounded' name='entry' type='dictionary_entry'/>
        </xs:sequence>
        <xs:attribute name='conceptref' use='required' type='xs:NCName'/>
    </xs:complexType>
</xs:element>
<xs:complexType name='dictionary_entry'>
    <xs:annotation>
        <xs:documentation>Entity Dictionary Entry: Entity that has a 'literal', i.e. the surface form, and the 'value' for ancillary use.</xs:documentation>
    </xs:annotation>
    <xs:attribute name='literal' use='required'/>
    <xs:attribute name='value' use='optional'/>
    <xs:attribute name='protected' use='optional' type='xs:boolean' default='false'/>
    <xs:attribute name='sourceref' use='optional' type='xs:NCName'/>
</xs:complexType>