Ontology node

An ontology is a formal specification of the semantic schema of your model.

In Mix.nlu, the ontology includes the set of intents and entities, and the relationships between them. The intents and entities you define in the ontology are used to annotate your training data, and thus form the interface between the NLU and your client application.

The ontology is the central schema for organizing your model and its sample data. The intents, entities, and associations between them are all stored in the ontology.

Ontology XML meta

<ontology>
    <intents>
        <intent name="str">
            <links>
                <link conceptref="str"/>
            </links>
        </intent>
    </intents>
    <concepts>
        <concept name="str" freetext="bool">
            <settings>
                <setting name="str" value="str"/>
            </settings>
            <relations>
                <relation type="str" conceptref="str" />
            </relations>
        </concept>
    </concepts>
</ontology>

Each intent is linked to zero or more entities. These are the entities that you can use when annotating entities in training samples that belong to the intent. They are also the full set of entities that can be returned in the JSON NLU results for this intent. You can think of the links as parameters to a method.

Samples labeled with an intent will only allow annotation of entities that are linked to the intent.

Entity data types

The following entity data types can be included in a TRSX file:

Entity data types
Type Description
not_set Data type is not set.
no_format Text data without any special format. Refers to the Generic data type in Mix.nlu and Mix.dialog.
yes_no Yes or no.
boolean True or false.
number A numerical quantity.
digits A sequence of digits from 0-9.
alphanum A sequence of letters or numbers, A-Z, a-z, 0-9.
date A YYYYMMDD date.
time An HHMM time.
amount A quantity with units, defined by the magnitude and units.
distance A measure of distance, including magnitude and distance unit.
temperature A measure of temperature, including possibly signed magnitude and units.

Entity collection methods

A collection method is related to how the set of possible values of the entity can be enumerated or defined.

Entity collection methods are as follows:

Entity collection methods
Type Description
List Default collection method of entities with data type no_format (generic).
Dynamic List If the dynamic attribute is true, the entity is defined as a Dynamic List.
Default is false.
Freeform If the freetext attribute is true, the entity is defined as a Freeform entity.
Default is false.
Rule-based Rule-based entities are defined with a GrXML grammar. To define an entity as rule-based, specify the name of the GrXML file in the ruleGrammarFileName attribute.
Relationship Entities can be extended by relationships to other entities.
To define a relationship entity, do not assign freetext or dynamic.
Instead, use a relations node.

Predefined entities

Nuance predefined entities can be used simply by referencing them via conceptref in ontology relation nodes and in sample annotations.

Entity relationships

There are three types of relationships that entities can have between entities.

Entity relationship types
Type Description
isA A entity can be related to zero-one entity with the isA relationship.
hasA A entity can be related to zero-to-many entities with the hasA relationship.
hasReferrers An entity can be referred to as a moment (REF_MOMENT), a person (REF_PERSON), a place (REF_PLACE), or a thing (REF_THING). See Anaphoras for details.

Note that isA and hasA are mutually exclusive.

For example, consider a flight application, with the following entities: City, origin_city, destination_city, and itinerary. The following relationships could be defined:

  • origin_city isA city
  • destination_city isA city
  • itinerary hasA origin_city
  • itinerary hasA destination_city

Ontology node specification

The ontology node is defined as follows:

  • The ontology node contains zero-one intents node and concepts node.
  • The ontology node contains the optional attribute base, which is currently not used.

Intents node

The intents node contains the ontology intents and is defined as follows:

  • The intents node contains zero-many intent nodes.
  • Each intent node defines a specific intent and contains zero-one links node.

Each intent node has the following attributes:

Intent node attributes
Attribute Required? Description
name Required Name of the intent. For example: FIND_MOVIE.
sourceref Optional Source of the intent. For example: DTV_Domain.

An intent is linked to a set of entities. The links node describes the entities that can be used in sample annotations for this intent and are returned in the JSON results.

The links node contains zero-many link nodes.

Each link node has the following attributes:

Link node attributes
Attribute Required? Description
conceptref Required Name of the entity associated with this intent.
This entity is defined in a concept node (see below).
sourceref Optional Source of the link. For example: DTV_Domain.

Concepts node

The concepts node contains the ontology entities and is defined as follows:

  • The concepts node contains zero-many concept nodes.
  • Each concept node defines a single entity.
  • Each concept node contains zero-one settings, relations, and regex node.

Each concept node has the following attributes:

Concept node attributes
Attribute Required? Description
name Required Name of the entity.
dataType Optional Type of data the entity contains. See Entity data types for more information.
freetext Optional true for a freeform entity; otherwise, false (default). See Entity collection methods.
dynamic Optional true for a dynamic entity; otherwise, false (default). See Entity collection methods.
ruleGrammarFileName Optional For rule-based entities, specifies the name of the GrXML file that defines the entity and its relative location in the TRSX file. See Entity collection methods.

Relations node

The relations node specifies the relation between entities. Relations can be of type isA, hasA, or hasReferrers. See Entity relationships for more information.

The relations node contains zero-many relation nodes.

Each relation node has the following attributes:

Relation node attributes
Attribute Required? Description
type Required Type of relation. Can be of type isA, hasA, or hasReferrers. See Entity relationships.
conceptref Required Name of entity to which the relation applies.
sourceref Optional Source of the relation. For example: DTV_Domain.

Note the following:

  • The relation node cannot contain two isA relations.
  • isA and hasA are mutually exclusive.

Settings node

The settings node defines settings that apply to the entity.

Settings node attributes
Setting Required? Description
isSensitive Optional When true, user sensitive data is masked in logs. Default value is false.
canonicalize Optional Specifies whether canonicalization is enabled or not. When true, values are returned for entities in the JSON results. Set to false if values are not required, for example, for performance optimization. Default value is true.

Settings schema

 <ontology base="http://localhost:8080/resources/ontology-1.0.xml">
        <concepts>
            <concept name="PAYMENT_DATE"/>
            <concept name="CCV">
                <settings>
                    <setting name="isSensitive" value="true"/>
                </settings>
            </concept>
            <concept name="CREDIT_CARD_NUMBER">
                <settings>
                    <setting name="isSensitive" value="true"/>
                </settings>
            </concept>
        </concepts>
 </ontology>

Regex node

The regex node defines the regex pattern for regex-based entities. For example, a phone number entity might have the following regex node: (\+\d{1,2}\s)?\(?\d{3}\)?[\s.-]\d{3}[\s.-]\d{4}

Ontology node example

In this example, there is one use case, SEARCH, and two entities are used as part of that use case: the query and the engine to use when searching.

<ontology base="https://developer.nuance.com/mix/nlu/trsx/ontology-1.0.xml">
    <intents>
        <intent name="SEARCH">
            <links>
                <link conceptref="SEARCH_ENGINE"/>
                <link conceptref="SEARCH_QUERY"/>
            </links>
        </intent>
    </intents>
    <concepts>
        <concept name="SEARCH_QUERY" freetext="true"/>
        <concept name="SEARCH_ENGINE"/>
    </concepts>
</ontology>

Ontology schema

<xs:element name='ontology'>
    <xs:annotation>
        <xs:documentation>Project Ontology: Data contract consisting of Intents, Entities, and their relations and properties.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
        <xs:sequence>
            <xs:element minOccurs='0' maxOccurs='1' ref='intents'/>
            <xs:element minOccurs='0' maxOccurs='1' ref='concepts'/>
        </xs:sequence>
        <xs:attribute name='base' use='optional' type='xs:anyURI'/>
    </xs:complexType>
</xs:element>
<xs:element name='intents'>
    <xs:annotation>
        <xs:documentation>Ontology Intents: App use cases, utilized as classifications for samples.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
        <xs:sequence>
            <xs:element minOccurs='0' maxOccurs='unbounded' ref='intent'/>
        </xs:sequence>
    </xs:complexType>
</xs:element>
<xs:element name='intent'>
    <xs:annotation>
        <xs:documentation>Intent: A particular use case, e.g. "turn_tv_on" or "stop_microwave".</xs:documentation>
    </xs:annotation>
    <xs:complexType>
        <xs:sequence>
            <xs:element minOccurs='0' maxOccurs='1' ref='links'/>
        </xs:sequence>
        <xs:attribute name='name' use='required' type='xs:NCName'/>
        <xs:attribute name='sourceref' use='optional' type='xs:NCName'/>
    </xs:complexType>
</xs:element>
<xs:element name='links'>
    <xs:annotation>
        <xs:documentation>An intent is linked to a set of entities. Samples within the intent can be annotated only with the linked entities.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
        <xs:sequence>
            <xs:element minOccurs='0' maxOccurs='unbounded' ref='link'/>
        </xs:sequence>
    </xs:complexType>
</xs:element>
<xs:element name='link'>
    <xs:annotation>
        <xs:documentation>Intent link: Specific entities that are applicable in the context of the defined Intent.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
        <xs:attribute name='conceptref' use='required' type='xs:NCName'/>
        <xs:attribute name='sourceref' use='optional' type='xs:NCName'/>
    </xs:complexType>
</xs:element>
<xs:element name='concepts'>
    <xs:annotation>
        <xs:documentation>Ontology entities: Specific details as part of the given use case, to guide decision making.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
        <xs:sequence>
            <xs:element minOccurs='0' maxOccurs='unbounded' ref='concept'/>
        </xs:sequence>
    </xs:complexType>
</xs:element>
<xs:element name='concept'>
    <xs:annotation>
        <xs:documentation>Entity: Possibly list based (static or dynamic) or freetext - these are parsed within the context of an Intent.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
        <xs:all>
            <xs:element minOccurs='0' maxOccurs='1' ref='settings'/>
            <xs:element minOccurs='0' maxOccurs='1' ref='regex'/>
            <xs:element minOccurs='0' maxOccurs='1' ref='relations'/>
        </xs:all>
        <xs:attribute name='name' use='required' type='xs:NCName'/>
        <xs:attribute name='dataType' use='optional' type='data_type'/>
        <xs:attribute name='freetext' use='optional' type='xs:boolean' default='false'/>
        <xs:attribute name='dynamic' use='optional' type='xs:boolean' default='false'/>
        <xs:attribute name='ruleGrammarFileName' use='optional' type='xs:string'/>
        <xs:attribute name='sourceref' use='optional' type='xs:NCName'/>
    </xs:complexType>
</xs:element>
<xs:simpleType name='data_type'>
    <xs:restriction base='xs:string'>
        <xs:enumeration value='not_set'/>
        <xs:enumeration value='no_format'/>
        <xs:enumeration value='yes_no'/>
        <xs:enumeration value='boolean'/>
        <xs:enumeration value='number'/>
        <xs:enumeration value='digits'/>
        <xs:enumeration value='alphanum'/>
        <xs:enumeration value='date'/>
        <xs:enumeration value='time'/>
        <xs:enumeration value='amount'/>
        <xs:enumeration value='distance'/>
        <xs:enumeration value='temperature'/>
    </xs:restriction>
</xs:simpleType>
<xs:element name='regex'/>
<xs:element name='relations'>
    <xs:annotation>
        <xs:documentation>Entity Relations: It is possible to inherit from an entity in some fashion. The following types can be described: isA, hasA, and hasReferrers. </xs:documentation>
    </xs:annotation>
    <xs:complexType>
        <xs:sequence>
            <xs:element minOccurs='0' maxOccurs='unbounded' ref='relation'/>
        </xs:sequence>
    </xs:complexType>
</xs:element>
<xs:element name='relation'>
    <xs:annotation>
        <xs:documentation>Relation: Type of linkage between entities -- isA, hasA, or hasReferrers.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
        <xs:attribute name='type' use='required' type='relation_type'/>
        <xs:attribute name='conceptref' use='required' type='xs:NCName'/>
        <xs:attribute name='sourceref' use='optional' type='xs:NCName'/>
    </xs:complexType>
</xs:element>
<xs:simpleType name='relation_type'>
    <xs:restriction base='xs:string'>
        <xs:enumeration value='isA'/>
        <xs:enumeration value='hasA'/>
        <xs:enumeration value='hasReferrers'/>
    </xs:restriction>
</xs:simpleType>
<xs:element name='settings'>
    <xs:annotation>
        <xs:documentation>Entity Settings: Properties on the entity that can be altered, e.g. "canonicalize".</xs:documentation>
    </xs:annotation>
    <xs:complexType>
        <xs:sequence>
            <xs:element minOccurs='0' maxOccurs='unbounded' ref='setting'/>
        </xs:sequence>
    </xs:complexType>
</xs:element>
<xs:element name='setting'>
    <xs:annotation>
        <xs:documentation>Entity Setting: Specific name-value pair to assign to the Entity.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
        <xs:attribute name='name' use='required'/>
         <xs:attribute name='value' use='required'/>
    </xs:complexType>
</xs:element>