Conversation Description Language

The OpenDialog CDL

This is provided as a reference for those interested in understanding in detail the approach that OpenDialog takes. We use this reference to define the behaviour of the conversation engine and support import and export of conversational applications within OpenDialog. 
This reference is work in progress.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here.
This document is licensed under The Apache License, Version 2.0.
Introduction
The OpenDialog Conversation Description Language specification defines a standard, implementation agnostic, way of describing conversations between participants in a conversational application and the semantics through which that conversation would be interpreted or executed through a conversational engine. 
The OpenDialog CDL can be used to capture conversational patterns and then provided to an appropriate conversation engine for execution. 
Definitions  
CDL Document
A CDL document is a document that describes an aspect of a conversational application using the CDL. It conforms to the 1.2 Yaml spec.  
Component
A component is a part of a CDL specification that performs a specific function and has a specific meaning. Examples of components are actions, interpreters, operations and contexts.
Scenario
A scenario is a collection of conversations around a specific goal. In terms of the underlying OpenDialog concepts a scenario is an Electronic Institution. A scenario, through conversations, defines the expected set of interactions between participants in the scenario, as well as rules that govern the overall behavior of the scenario or individual participants. 
Conversation
A conversation captures a specific high-level activity as part of a scenario. For example in a Restaurant Scenario you may have a Collect Order conversation or a Settle Bill conversation. 
Scene
A scene is a subset of interactions within a scenario that are semantically, contextually and operationally related. For example in the Collect Order conversation you may have a Collect Starter Orders scene before you move on to the Collect Main Dishes scene. 
Turn
A turn is a specific exchange between participants in the scene. Typically, it involves the user requesting something and then the application responding. That single request-response exchange represents a turn and a scene is made of multiple turns. The CDL provides means to define different behaviours for turns that enable us to compose them into sophisticated scenes without having to define static flows through exchanges. 
Attribute
An attribute is a describable feature of the environment. The set of all attributes used within a conversational application provide a light-weight domain ontology for that conversation application. We use attributes to describe both features of the conversational application itself (e.g. current conversation, user etc) and of the application domain (price, color, etc). 
Action
An action changes the environment within which a conversational application operates by manipulating attributes of that environment. In practical terms that means communicating with internal or external APIs to affect changes in services that interface with the conversational application.
Interpreters
An interpreter transforms an input from a participant of a conversation, typically the user, to a specific intent that the conversation engine can reason about.  
Operation
An operation accepts a set of environment attributes, performs a calculation and returns true of false based on some success criteria for that operation. Operations are used in conditions.
Context 
Contexts are the mechanisms through which we store and access information relevant to a Scenario. Information is stored in the form of attributes. Context typically have a specific scope - either across an entire scenario, around a user, a conversation, or a scene. Conversational applications can define their own domain-specific contexts.
Behavior
A behaviour can be associated with a Scenario, Conversation, Scene and Turn and represents a directive to the conversational engine that provides additional context around how that specific components should be treated. 
Specification
Scenario
A scenario is defined as a set of related conversations and the associated OD components that are required to execute those conversations. A scenario is described through a scenario document. 
Here is an example scenario document:
example_scenario.yaml
od_cdl_version: 1.0
type: scenario
name: Example Scenario
id: example_scenario
description: This is a long text describing the scenario that will be used in the UI.
behavior:
 - placeholder
default_interpreter: interpreter.core.nlp 
conditions:
  - condition:
      operation: gte
      parameters:
        - id: value_a
          value: _intent.price
        - id: value_b
          value: 10conversations:
  - id : conversation1
    ref: conversation1/conversation.yaml
  - id : conversation2
    ref: conversation2/some_conversation.yaml
  - id : conversation3
    ref: conversation3/theother_conversaiton.yaml
​
Field Name
Type
Description
od_cdl_version
string
This REQUIRED string MUST be the semantic version number of the OD CDL specification that the scenario document adheres to. 
type
string
REQUIRED - the type of document that is defined below
name
string
MAY - a scenario document may have a user-friendly name.
description
string
MAY - a scenario document may have a description of that scenario
behavior
collection of strings
MAY - a scenario may have a collection of behavior directives that direct the conversation engine to treat the scenario in a given way
id
string
REQUIRED - a scenario is required to have an id. The same OD system cannot support two scenarios with the sane id. IDs can contain alphanumeric characters [a-zA-Z09] and underscores _ only. 
conversations
yaml collection
MAY - a conversation collection block may exist. (n.b. a scenario without any conversations is not very useful but can exist from a spec perspective)
default_interpreter
string
A scenario MAY define a defaultInterpeter that will be used for any intent that does not have an interpreter defined itself (or any of the components that lead to that intent)
conditions
collection of conditions (see Condition)
A scenario MAY define conditions that need to hold true for that scenario to be considered. 
Conversation Collection Item
Yaml Collection Item 
A Conversation collection item MUST have an id representing the conversation, it MAY have a reference ref to a conversation document implementing that conversation. The reference is a path relative to the root from the scenario document. 
Conversation
A conversation is a self-contained set of exchanges of intents, between participants in the conversation grouped in scenes and then turns. 
Here is an example conversation document:
od_cdl_version: 1.0
type: conversation
name: Example Conversation
id: example_conversation
description: This is a long text describing the conversation that will be used in the UI.
behaviors:
 - starting
 - open
 - placeholder
default_interpreter: interpreter.core.nlp 
conditions:
 - condition:
      operation: gte
      parameters:
        - id: value_a
          value: _intent.price
        - id: value_b
          value: 10
scenes:
  - scene: 
      name: Example Scene
      description: A long description for the scene
      id: example_scene
      behaviors:
        - open
        - starting
      turns:
        - turn:
          id: turn_id
          name: Turn Name
          behaviors:
           - open
           - starting
           - single
          intents:
            - request: 
              - user:
                  id: intent.core.welcome
            - response:      
               - app:
                  id: intent.core.onboard    
              
            
​
Field Name
Type
Description
od_cdl_version
string
REQUIRED - this string must be the semantic version number of the OD CDL specification that the conversation document adheres to. 
type
string
REQUIRED - the type of document that is defined below
name
string
MAY - a conversation document may have a user-friendly name.
description
string
MAY - a conversation document may have a description of that conversation
id
string
REQUIRED - a conversation is required to have an id. The same OD scenario cannot support two conversations with the sane id. IDs can contain alphanumeric characters [a-zA-Z09] and underscores _ only. 
behaviors
collection of strings
MAY - a conversation may have a collection of behavior directives that direct the conversation engine to treat the conversation in a specific way. An starting behavior indicates that this is a valid conversation to start a scenario with while an open behavior indicates that the conversation is open to be selected if the user is already in that scenario. Starting conversations may or may not be open conversations. 
default_interpreter
string
A scenario MAY define a default_interpeter that will be used for any intent that does not have an interpreter defined itself (or any of the components that lead to that intent) 
conditions
collection of conditions (see Condition)
A conversation MAY define conditions that need to hold true for that conversation to be considered. 
scenes
colelction of scenes (see Scene)
A conversation MAY define a set of scenes 
Conversation Behaviors
starting A starting behavior indicates that this is a valid conversation to start the scenario with if the user was not already actively interacting with the conversational application through the scenario. 
Scene
A scene captures the expected exchange of intents between participants in a scene. A scene is part of a conversation document. 
scenes:
  - scene: 
      name: Example Scene
      description: A long description for the scene
      id: example_scene
      conditions:
        - condition:
            operation: gte
            parameters:
              - id: value_a
                value: _intent.price
              - id: value_b
                value: 10
      behaviors:
        - open
        - starting
      default_interpreter: interpreter.core.nlp  
      turns:
        - turn:
          id: turn_id
          name: Turn Name
          behaviors:
           - open
           - starting
           - single
          intents:
            - user:
              id: intent.core.welcome
            - app:
              id: intent.core.onboard    
 
​
Field Name
Type
Description
scenes
string
Scenes MUST be defined within a scenes collection
name
string
MAY - a scene may have a user-friendly name.
description
string
MAY - a scene may have a description of that scene
id
string
REQUIRED - a scene is required to have an id. The same OD scenario cannot support two conversations with the sane id. IDs can contain alphanumeric characters [a-zA-Z09] and underscores _ only. 
conditions
collection of conditions (see Condition)
A scene MAY define conditions that need to hold true for that scene to be considered. 
behaviors
collection of strings
A scene MAY define a set of behaviours that will be taken into consideration when evaluating the scene in a conversational context
default_interpreter
string
A scene MAY define a default_interpeter that will be used for any intent that does not have an interpreter defined itself (or any of the components that lead to that intent) 
turns
collection of Turns (see Turn)
A scene MUST describe at least one conversational turn. 
Scene Behaviors
starting A starting behavior indicates that this is a valid scene to start the conversation with if the user was not already actively in an ongoing conversation that the scene is part of. 
open An open scene indicates a scene that should always be considered within a conversation if the current scene the user is in does not have an appropriate matching intent.  
Turn
A turn is a specific exchange of intents between participants in a scene.
        - turn:
          id: turn_id
          name: Turn Name
          behaviors:
           - open
           - starting
           - repeat:
             - param: order
               value: 2
          default_interpreter: intent.core.nlp     
          valid_origins:
           - turn-id
           - turn-id 
          intents:
            - request:
              - user:
                  id: intent.core.welcome1
              - user:
                  id: intent.core.welcome2               
            - response:    
              - app:
                  id: intent.core.onboard1    
              - app:
                  id: intent.core.onboard2    
​
​
Field Name
Type
Description
turns
string
Turns MUST be defined within a turns collection
name
string
MAY - a turn may have a user-friendly name.
id
string
REQUIRED - a turn is required to have an id. The same scene cannot support two turns with the sane id. IDs can contain alphanumeric characters [a-zA-Z09] and underscores _ only. 
conditions
collection of conditions (see Condition)
A turn MAY define conditions that need to hold true for that turn to be considered. 
behaviors
collection of strings
A turn MAY define a set of behaviours that will be taken into consideration when evaluating the scene in a conversational context. A behavior MAY have associated parameters.
default_interpreter
string
A turn MAY define an interpreter that will be used unless the intents within the turn define an interpreter.
valid_origins
collection of turn ids
A turn MAY define a set of turn ids that are valid origins for this turn. The turn that defines a valid origin is the destination turn and a turn that is defined as a valid origin is the originating turn. A turn that defines valid origins will only be considered if the conversational state is currently in one of the indicated origin turns. 
intents
collection of Intents (see Intent)
A turn MUST describe at least one intent from one participant.
Intent
An intent is a specific exchange that a participant in a conversation says. 
          intents:
            - user:
                id: intent.core.welcome
                interpreter: interpreter.core.Luis
                expected_attributes:
                  - item.price
                      if-not-present-transition:
                        conversation: some_conversation
                        scene: another_scene
                        turn: turn_id
                  - item.color
                behaviors:
                  - completing
                transition:
                 conversation: some_conversation
                 scene: another_scene
                 turn: turn_id
                listens:
                 - intent.core.somethingElse
                 - intent.core.new 
                virtual:
                  - user:
                    id: intent.core.Virtual 
                actions:
                  - action:
                    id: action.core.CalculateDiscount
                    attribute_input:
                      - id: item.price
                    attribute_output:
                      - id: item.discounted_price  
                conditions:
                  - condition:
                      operation: gte
                      parameters:
                        - id: value_a
                          value: _intent.price
                        - id: value_b
                          value: 10
            - app:
                id: intent.core.onboard    
Field Name
Type
Description
intents
string
Intents MUST be defined within an intents collection
user | app
string
An intent MUST be said by either the user or the app. 
id
string
An intent MUST have an intent id
interpreter
string
An intent MAY have an interpreter id - if an interpreter is defined we use that interpreter to interpret utterances in cases where that utterance is expected to match to the intent in question. 
completes
boolean
An intent MAY indicate that it completes a conversation. In this case the conversation is considered completed and following this intent no additional intents are exchanged. If this was an intent from the user it means that we will not respond to the user. If this was an intent from the bot it means that once we respond to the user we will consider the existing conversation completed. 
transition
Collection
An intent may cause a transition that will move the conversational state to a new conversation or scene or turn. A transition MUST define at least one of the three and there are different logics applied to how we handle the transition based on what is available.  
actions
collection of Actions (see Actions)
An intent MAY define a series of actions that are performed if the intent in question is selected as the next intent in the scene. 
conditions
collection of conditions (see Condition)
An intent MAY define conditions that need to hold true for that intent to be considered. 
Transition
A transition is a directive to move the conversational state to a specific new conversation, scene or turn. Transitions are triggered at the intent level. For a transition to succesfully move the state there are two requirements:
The new state (turn, scene or conversation) has an opening intent that matches the originating intent.
The new state (turn, scene or conversation) starts with the next speaker (e.g. when a user causes a transition that moves us to a turn where the app is the first participant) and the participant explicitly states that it is listening for an out of scene intent that matches the originating intent. 
Turn Transition
A turn transition takes place when the CDL only defines a turn. The conversation engine should look for other turns within the same scene that meet one of the two requirements above. 
Scene Transition
A scene transition means that we will look for open turns in the new scene that match the requirements
Scene Transition with Turn
A scene transition with turn means that we will move to the new scene and only evaluate the specified turn against the requirements
Conversation Transition
A conversation transtition means that we will evaluate all scenes within the new conversation for the requirement.
Conversation Transition with Scene
A conversation transition with scene that we will only evaluate a specific scene within the new conversation
Conversation Transition with Scene and Turn 
A conversation transition with scene and turn means that we will evaluate only the specific turn within the new conversations and scene. 
Condition
A condition is an operation to be performed that can only return TRUE or FALSE. We can optionally supply parameters that will be taken into consideration when performing the operation. 
These parameters have an id (a label that provides an indication of what they are) and can either be raw values or dynamic values extracted from attributes stored in contexts. 
The values associated with attributes are typically reference comparison points. For example, below the operation will evaluate the total order price is greater than or equal to the price value. 
Conditions are always presented within a conditions block. All conditions must evaluate to true for the condition block to pass. 
 conditions:
    - condition:
      operation: gte
      parameters:
        - id: value_a
          value: _intent.price
        - id: value_b
          value: 10
In the condition example above we have a gte operation (greater than or equal) that accepts two parameters. value_ais compare to value_b to determine whether it is greater than or equal to it. value_a is the price attribute stored in the _intent context and value_b  is the reference value we want to compare to, which is 10. 
Action
An action is an operation that may accept a set of attributes as inputs, performs an action (typically interaction with outside APIs) and may return a set of attributes as outputs. 
                  - action:
                    id: action.core.CalculateDiscount
                    attribute_input:
                      - id: item.price
                    attribute_output:
                      - id: item.discounted_price  
​

Developing With OpenDialog - Previous

Actions

Last updated 4 weeks ago

Field Name	Type	Description
`od_cdl_version`	string	This REQUIRED string MUST be the semantic version number of the OD CDL specification that the scenario document adheres to.
`type`	string	REQUIRED - the type of document that is defined below
`name`	string	MAY - a scenario document may have a user-friendly name.
`description`	string	MAY - a scenario document may have a description of that scenario
`behavior`	collection of strings	MAY - a scenario may have a collection of behavior directives that direct the conversation engine to treat the scenario in a given way
`id`	string	REQUIRED - a scenario is required to have an id. The same OD system cannot support two scenarios with the sane id. IDs can contain alphanumeric characters `[a-zA-Z09]` and underscores `_` only.
`conversations`	yaml collection	MAY - a conversation collection block may exist. (n.b. a scenario without any conversations is not very useful but can exist from a spec perspective)
`default_interpreter`	string	A scenario MAY define a defaultInterpeter that will be used for any intent that does not have an interpreter defined itself (or any of the components that lead to that intent)
`conditions`	collection of conditions (see Condition)	A scenario MAY define conditions that need to hold true for that scenario to be considered.
Conversation Collection Item	Yaml Collection Item	A Conversation collection item MUST have an `id` representing the conversation, it MAY have a reference `ref` to a conversation document implementing that conversation. The reference is a path relative to the root from the scenario document.

Field Name	Type	Description
`od_cdl_version`	string	REQUIRED - this string must be the semantic version number of the OD CDL specification that the conversation document adheres to.
`type`	string	REQUIRED - the type of document that is defined below
`name`	string	MAY - a conversation document may have a user-friendly name.
`description`	string	MAY - a conversation document may have a description of that conversation
`id`	string	REQUIRED - a conversation is required to have an id. The same OD scenario cannot support two conversations with the sane id. IDs can contain alphanumeric characters `[a-zA-Z09]` and underscores `_` only.
`behaviors`	collection of strings	MAY - a conversation may have a collection of behavior directives that direct the conversation engine to treat the conversation in a specific way. An starting behavior indicates that this is a valid conversation to start a scenario with while an open behavior indicates that the conversation is open to be selected if the user is already in that scenario. Starting conversations may or may not be open conversations.
`default_interpreter`	string	A scenario MAY define a default_interpeter that will be used for any intent that does not have an interpreter defined itself (or any of the components that lead to that intent)
`conditions`	collection of conditions (see Condition)	A conversation MAY define conditions that need to hold true for that conversation to be considered.
`scenes`	colelction of scenes (see Scene)	A conversation MAY define a set of scenes

Field Name	Type	Description
`scenes`	string	Scenes MUST be defined within a `scenes` collection
`name`	string	MAY - a scene may have a user-friendly name.
`description`	string	MAY - a scene may have a description of that scene
`id`	string	REQUIRED - a scene is required to have an id. The same OD scenario cannot support two conversations with the sane id. IDs can contain alphanumeric characters `[a-zA-Z09]` and underscores `_` only.
`conditions`	collection of conditions (see Condition)	A scene MAY define conditions that need to hold true for that scene to be considered.
`behaviors`	collection of strings	A scene MAY define a set of behaviours that will be taken into consideration when evaluating the scene in a conversational context
`default_interpreter`	string	A scene MAY define a default_interpeter that will be used for any intent that does not have an interpreter defined itself (or any of the components that lead to that intent)
`turns`	collection of Turns (see Turn)	A scene MUST describe at least one conversational turn.

Field Name	Type	Description
`turns`	string	Turns MUST be defined within a `turns` collection
`name`	string	MAY - a turn may have a user-friendly name.
`id`	string	REQUIRED - a turn is required to have an id. The same scene cannot support two turns with the sane id. IDs can contain alphanumeric characters `[a-zA-Z09]` and underscores `_` only.
`conditions`	collection of conditions (see Condition)	A turn MAY define conditions that need to hold true for that turn to be considered.
`behaviors`	collection of strings	A turn MAY define a set of behaviours that will be taken into consideration when evaluating the scene in a conversational context. A behavior MAY have associated parameters.
`default_interpreter`	string	A turn MAY define an interpreter that will be used unless the intents within the turn define an interpreter.
`valid_origins`	collection of turn ids	A turn MAY define a set of turn ids that are valid origins for this turn. The turn that defines a valid origin is the destination turn and a turn that is defined as a valid origin is the originating turn. A turn that defines valid origins will only be considered if the conversational state is currently in one of the indicated origin turns.
`intents`	collection of Intents (see Intent)	A turn MUST describe at least one intent from one participant.

Field Name	Type	Description
`intents`	string	Intents MUST be defined within an `intents` collection
`user \| app`	string	An intent MUST be said by either the user or the app.
`id`	string	An intent MUST have an intent id
`interpreter`	string	An intent MAY have an interpreter id - if an interpreter is defined we use that interpreter to interpret utterances in cases where that utterance is expected to match to the intent in question.
`completes`	boolean	An intent MAY indicate that it completes a conversation. In this case the conversation is considered completed and following this intent no additional intents are exchanged. If this was an intent from the user it means that we will not respond to the user. If this was an intent from the bot it means that once we respond to the user we will consider the existing conversation completed.
`transition`	Collection	An intent may cause a transition that will move the conversational state to a new conversation or scene or turn. A transition MUST define at least one of the three and there are different logics applied to how we handle the transition based on what is available.
`actions`	collection of Actions (see Actions)	An intent MAY define a series of actions that are performed if the intent in question is selected as the next intent in the scene.
`conditions`	collection of conditions (see Condition)	An intent MAY define conditions that need to hold true for that intent to be considered.