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 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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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. |
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 |
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. 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. |
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. 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. |
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. |
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:
- 1.The new state (turn, scene or conversation) has an opening intent that matches the originating intent.
- 2.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.
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.
A scene transition means that we will look for open turns in the new scene that match the requirements
A scene transition with turn means that we will move to the new scene and only evaluate the specified turn against the requirements
A conversation transtition means that we will evaluate all scenes within the new conversation for the requirement.
A conversation transition with scene that we will only evaluate a specific scene within the new conversation
A conversation transition with scene and turn means that we will evaluate only the specific turn within the new conversations and scene.
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. 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
Last modified 1yr ago