Version: 6.3.3

CAMEL Specification

The CAMEL specification defines a standard, language-agnostic, and platform-agnostic language that describes the composition and orchestration of skills, data, and machine learning models to define and execute a Cognitive Agent that is used to augment human intelligence.

CAMEL is an acronym that stands for "Cognitive Agent Modeling and Execution Language" and can be thought of as a language for programming Cognitive Agents.

See the Glossary for definitions of many of the terms used in this specification.

Key words

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 CognitiveScale End-User License Agreement (EULA).

Versions

The CAMEL Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.

The major.minor portion of the semver (for example 1.0) SHALL designate the CAMEL feature set. Typically, .patch versions address errors in this document, not the feature set. Tooling which supports CAMEL 1.0 SHOULD be compatible with all CAMEL 1.0.* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between 1.0.0 and 1.0.1 for example.

Subsequent minor version releases of the CAMEL Specification (incrementing the minor version number) SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical 1.1.0 specification SHOULD be usable with tooling designed for 1.0.0.

A CAMEL document compatible with CAMEL 1.*.* contains a required camel field which designates the semantic version of the CAMEL specification that it uses.

Format

A CAMEL document that conforms to the CAMEL Specification is itself a JSON object, which may be represented either in JSON or YAML format.

For example, if a field has an array value, the JSON array representation will be used:

{
"field": [ 1, 2, 3 ]
}

All field names in the specification are case sensitive.

In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:

Data Types

Primitive data types in CAMEL are based on the types supported by the JSON Schema Specification Wright Draft 00. Note that integer as a type is also supported and is defined as a JSON number without a fraction or exponent part. Using null as a type is not supported. Data types are defined using the Parameters, which is an extended subset of JSON Schema Specification Wright Draft 00.

Primitives have an optional modifier property: `format`. CAMEL uses several known formats to define in fine detail the data type being used. However, to support documentation needs, the `format` property is an open `string`-valued property, and can have any value.

Formats such as "email", "uuid", and so on, MAY be used even though undefined by this specification.

Types that are not accompanied by a format property follow the type definition in the JSON Schema. Tools that do not recognize a specific format MAY default back to the type alone, as if the format is not specified.

The formats defined by the CAMEL specification are:

Common NameTypeFormatComments
integerintegerint32signed 32 bits
longintegerint64signed 64 bits
floatnumberfloat
doublenumberdouble
stringstring
bytestringbytebase64 encoded characters
binarystringbinaryany sequence of octets
booleanboolean
datestringdateAs defined by full-date - RFC3339
dateTimestringdate-timeAs defined by date-time - RFC3339
objectobjectembedded/nested object
arrayarrayA valid typeembedded/nested array

Examples

An integer

{
"type": "integer"
}

A double

{
"type": "number",
"format": "double"
}

A base64 encoded binary

{
"type": "string",
"format": "byte"
}

A date-time string

{
"type": "string",
"format": "date-time"
}

Embedded object

{
"type": "object"
}

Embedded array of numbers

{
"type": "array",
"format": "number"
}

Rich Text Formatting

Throughout the specification description fields are noted as supporting CommonMark markdown formatting. Where CAMEL tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.

Schema

In the schema descriptions that follow, if a field is not explicitly REQUIRED or described with a MUST or SHALL, it can be considered OPTIONAL.

Common Fields

The following fields are common across many CAMEL resources and will be referenced throughout the specification.

Field NameTypeDescription
camelstringREQUIRED. This string MUST be the semantic version number of the CAMEL Specification version that the CAMEL document uses. The camel field SHOULD be used by tooling specifications and clients to interpret the CAMEL document. This is not related to the resource version string.
namestringREQUIRED. The fully qualified name of the resource.
titlestringOPTIONAL. The human friendly name given to a resource.
descriptionstringOPTIONAL. A free-text account of a resource. MAY include rich text. MAY be a reference to external documentation using a URL Reference Object.
tagsTag ObjectOPTIONAL. An array of tags used to annotate the resource.

System Fields

A CAMEL document MAY include system fields. Any field that starts with a _ is considered a system field. Some common system fields are described below:

Field NameTypeDescription
_versionintegerThe resource version number.
_createdAtdateTimeCaptures the date and time of resource creation.
_updatedAtdateTimeCaptures the date and time of last resource update.
_idstringA unique identifier assigned by the system to identify a resource.
_layoutanyUsed by tools to record visual layout settings.
_tenantIdstringA unique identifier identifying an account that owns the resource.

Common Objects

The following objects are common across many CAMEL resources and will be referenced throughout the specification.

Property Definition Object

The property definition object is used to declare a configurable property of a resource.

Property Definition Object: Fixed Fields

Field NameTypeDescription
namestringREQUIRED. The unique name of this property within the resource. Tools and libraries MUST use the name to uniquely identify the property, therefore, it is RECOMMENDED to follow common programming naming conventions.
titlestringREQUIRED.
descriptionstringOPTIONAL.
requiredbooleanOPTIONAL. Default value is false.
typestringREQUIRED. Must be one of Enum, String, Boolean, Number.
defaultValueanyOPTIONAL. The default value for this property.
validValuesstringREQUIRED. An array of valid values for use with the Enum property type. Ignored for other property types.
qualifiedBystringOPTIONAL. Scopes this property to another property value by name. For example, for a property named api-key where qualifiedBy: model=Synchronous, the user can set the api_key property only if Synchronous is selected as the model. Otherwise, the api_key property cannot be set.
securebooleanOPTIONAL. Default value is false.

Property Value Object

The property value object is used to set a property.

Property Value Object: Fixed Fields

Field NameTypeDescription
namestringThe property name.
valueanyThe property value.

Tag Object

The tag object is used to annotate resources with descriptive labels or categories to enable discovery.

Tag Object: Fixed Fields

Field NameTypeDescription
labelstringThe tag label.
valuestringThe tag value.

Parameter Object

The parameter object is used to define a list of ordered parameters used in a Message.

Parameter Object: Examples

Primitive types example: User, Item, Rating

parameters:
- name: uid
title: User ID
type: integer
format: int64
required: true
- name: iid
title: Item ID
type: integer
format: int64
required: true
- name: rating
title: Rating
type: number
format: double
required: true

Embedded objects and arrays example: News Article

parameters:
- name: articleId
title: Article ID
type: string
required: true
- name: headline
title: Headline
type: string
required: true
- name: text
title: Article Text
type: string
required: false
- name: imageLinks
title: Image Links
type: array
format: url
required: false
- name: feedInfo
title: Feed Information
type: object
required: false

Parameter Object: Fixed Fields

Field NameTypeDescription
namestringREQUIRED. The unique name of the parameter. The name SHOULD be a code friendly identifier.
titlestringOPTIONAL. See Resource Title.
descriptionstringOPTIONAL. See Resource Description.
typestringREQUIRED. One of the six valid types allowed by CAMEL: integer, number, boolean, string, object, array.
formatstringOPTIONAL. A descriptive format string like date, email, or double. See Data Types for a discussion of the built-in formats.
requiredbooleanOPTIONAL. Default false.

Reference Object

The reference object is used to declare a pointer to a resource such as a Dataset or Schema.

Reference Object: Examples

Dataset reference, used in "pass-by-value" scenarios:

{
"payload": {
"$ref": "examples/movies_dataset"
}
}

Schema reference, used in parameter declarations:

parameters:
- $ref: examples/MovieInformation

Reference Object: Fixed Fields

Field NameTypeDescription
$refstringREQUIRED. The Resource Name, including version if desired, of the resource this object is pointing to.

URL Reference Object

The URL reference object is used to declare a hyperlink to an external resource, such as external documentation, and can be used in description (see Resource Description) fields or other fields that support resource linking.

URL Reference Object: Examples

External documentation reference

{
"description": {
"$url": "http://example.com/external_markdown_doc.md"
}
}

URL Reference Object: Fixed Fields

Field NameTypeDescription
$urlstringREQUIRED. A valid RFC xxxxx URL pointing to an external resource that should be used as the value for the containing field.

Skill Object

This is the root document object of a CAMEL document that contains a Skill definition.

Skill Object: Examples

An example "Hello World" Skill is shown below:

camel: 1.0.0
name: default/hello_world
title: Hello World
description: The classic Hello World example.
properties:
-
name: lang
title: Language
description: The language to say hello in.
required: true
type: Enum
defaultValue: en
validValues:
- en
- es
- it
- de
inputs:
-
name: yourName
title: Your Name
parameters:
- name: name
type: string
description: The name to send
required: true
routing:
all:
action: default/hello_world
runtime: cortex/daemons
output: greeting
outputs:
-
name: greeting
title: Greeting
parameters:
- name: message
type: string
description: The greeting message

Skill Object: Fixed Fields

Field NameTypeDescription
camelstringREQUIRED. See CAMEL Specification Version.
namestringREQUIRED. See Resource Name.
titlestringREQUIRED. See Resource Title.
descriptionstringOPTIONAL. See Resource Description.
tagsTag ObjectOPTIONAL. See Resource Tags.
propertiesProperty ObjectOPTIONAL.
inputsSkill Input ObjectREQUIRED. An array of Input Objects. At least one Input is required.
outputsSkill Output ObjectOPTIONAL. An array of Output Objects.
datasetsDataset Reference ObjectOPTIONAL. An array of Dataset Reference Objects. Each reference declares a dependency on a Dataset that must be mapped at runtime.

Skill Input Object

This object defines an input message used by the Skill.

Skill Input Object: Fixed fields

Field NameTypeDescription
namestringREQUIRED.
titlestringREQUIRED.
parametersParameter Object| Reference ObjectREQUIRED.
routingRouting ObjectREQUIRED.

Skill Output Object

This object defines an output message used by the Skill.

Skill Output Object: Fixed fields

Field NameTypeDescription
namestringREQUIRED.
titlestringREQUIRED.
parametersParameter Object | Reference ObjectREQUIRED.

Routing Object

This object defines the routing rules for a Skill input. Skills route Messages received on an Input to an Action for processing and then to an Output. A Skill MUST define at least one routing rule for each Input. Messages can be routed based on properties or Message field values. The simplest form of routing is the all routing which routes all Messages received on a given Input to a single Action.

Routing Object: Examples

The ALL routing. Routes all messages to a single action.

routing:
all:
action: example/hello_world
output: greeting

Property based routing

routing:
property: model
default:
action: example/sentiment_python_pattern
output: sentiment
rules:
- match: Stanford Sentiment
action: example/sentiment_stanford
output: sentiment
- match: Microsoft Cognitive Services
action: example/sentiment_microsoft
output: sentiment
- match: IBM Watson
action: example/sentiment_watson
output: sentiment

Field based routing

routing:
field: language
default:
action: example/sentiment_english
output: sentiment
rules:
- match: es
action: example/sentiment_spanish
output: sentiment
- match: de
action: example/sentiment_german
output: sentiment
- match: it
action: example/sentiment_italian
output: sentiment

All Routing: Fixed fields

Field NameTypeDescription
actionstringREQUIRED. The Resource Name of the action to route to.
runtimestringOPTIONAL. The Resource Name of the action runtime to use. The default runtime is assumed if not provided.
outputstringREQUIRED. The name of the Output to route to.

Property Routing: Fixed fields

Field NameTypeDescription
propertystringREQUIRED. The name of the property to apply routing rules to.
defaultAll RoutingOPTIONAL. The default routing rule used if no property matches are made.
rulesRouting Rule ObjectREQUIRED. List of routing rules to apply to the specified property value.

Field Routing: Fixed fields

Field NameTypeDescription
fieldstringREQUIRED. The name of the Message field to apply routing rules to.
defaultAll RoutingOPTIONAL. The default routing rule used if no property matches are made.
rulesRouting Rule ObjectREQUIRED. List of routing rules to apply to the specified field value.

Routing Rule Object

This object defines a routing rule to apply to a value that comes from either a Skill property or Message field value.

Routing Rule Object: Fixed fields

Field NameTypeDescription
matchstringThe value to match.
actionstringREQUIRED. The Resource Name of the action to route to.
runtimestringOPTIONAL. The Resource Name of the action runtime to use. The default runtime is assumed if not provided.
outputstringREQUIRED. The name of the Output to route to.

Dataset Reference Object

This object defines how a Skill declares a dependency on a dataset that must be mapped to it at runtime.

Dataset Reference Object: Fixed fields

Field NameTypeDescription
namestringREQUIRED. The name of the reference.
titlestringOPTIONAL. A human friendly display name for the reference.
descriptionstringOPTIONAL. A description or documentation of the reference.
parametersParameter Object| Reference ObjectOPTIONAL. The fields expected in the dataset.
requiresWritebooleanOPTIONAL. Set to true to indicate that the mapped dataset must support writes.

Dataset Object

This is the root document object that contains a Dataset definition.

Dataset Object Examples

An example Dataset is shown below:

camel: 1.0.0
name: default/movie_info
title: Movie Information
description: Contains basic information about thousands of movies.
parameters:
- name: movieId
type: integer
- name: movieTitle
type: string
- name: releaseDate
type: string
- name: imdbUrl
type: string
format: url
- name: category
type: string
connections:
default:
name: cortex/content
type: managedContent
query:
- name: key
value: movielens/ML100K-Movies.csv
- name: contentType
value: CSV
- name: csv/delimiter
value: '|'
environments:
- environment: PROD
name: example/moviesdb
type: postgresql
query:
- name: query
value: "SELECT * FROM movies"

OR

camel: 1.0.0
name: default/movie_info
title: Movie Information
description: Contains basic information about thousands of movies.
parameters:
- name: $ref
value: cortex/UserItemRating
connections:
default:
name: cortex/content
type: managedContent
query:
- name: key
value: movielens/ML100K-Movies.csv
- name: contentType
value: CSV
- name: csv/delimiter
value: '|'
environments:
- environment: PROD
name: example/moviesdb
type: postgresql
query:
- name: query
value: "SELECT movie_id as movieId, title as movieTitle, release_date as releaseDate, imdb_url as imdbUrl, category FROM movies"

Dataset Object: Fixed Fields

Field NameTypeDescription
camelstringREQUIRED. See CAMEL Specification Version
namestringREQUIRED. See Resource Name.
titlestringREQUIRED. See Resource Title.
descriptionstringOPTIONAL. See Resource Description.
tagsTag ObjectOPTIONAL. See Resource Tags.
parametersParameters ObjectREQUIRED. Defines the fields included in this dataset. The dataset MAY include additional fields not defined here.
connectionsConnection Configuration ObjectREQUIRED. Data store connection configuration for this dataset.

Connection Configuration Object

This object defines the data source connection configuration for a Dataset. A Dataset MUST have at least one connection per deployed environment or MUST provide a default connection configuration that is used in environments where no environment specific connection is defined.

Connection Configuration Object: Fixed fields

Field NameTypeDescription
defaultConnection Reference ObjectOPTIONAL. The default connection to use in environments where no environment specific connection configuration exists.
environmentsConnnection Reference ObjectOPTIONAL. A list of environment specific connections to use for this dataset. Each object in this list MUST use the environment property to qualify which environment it applies to. If more than one connection for an environment is defined, only the first connection in the list will be used.

Connection Reference Object

This object defines the reference to a data source connection for a specific environment. It includes information about the type of connection (e.g. mongo, s3, etc.) as well as the query parameter configuration.

Connection Reference Object: Fixed fields

Field NameTypeDescription
namestringREQUIRED. The fully qualified name of the connection to use.
typestringREQUIRED. The name of the connection type.
queryProperty ValueOPTIONAL. Defines the default connection query parameters to use when reading from this connection. The definitions of these properties is provided by connection type object.
environmentstringOPTIONAL.

Message Object

This object defines the message format used for skill-to-skill and agent-to-skill communication.

Message Object: Fixed fields

Field NameTypeDescription
payloadPayload ObjectREQUIRED.
parametersParameter ObjectOPTIONAL.

Payload Object

This object is used in Messages to carry a payload sent for processing. Payloads have four different styles demonstrated in examples below:

  1. Inline Objects
  2. Inline Records
  3. Inline DataFrame
  4. DataSet Reference (e.g. pass-by-reference)

Payload Object: Examples

Payload with Inline Object

{
"payload": {"text": "Hello World"}
}

Payload with Inline Records

{
"payload":
{
"records": [
{},
{},
{}
]
}
}

Payload with Inline DataFrame

{
"payload":
{
"columns": []
"values": []
}
}

Payload with DataSet Reference

{
"payload": {"$ref": "default/MyDataSet"}
}

Payload Object: Fixed fields

Field NameTypeDescription
recordsanyOPTIONAL. An array of JSON objects representing dataset records. The fields of the these records MUST match the fields defined in the dataset.
columnsstringOPTIONAL. The column names that match the records containing in the values array. The column names MUST at least match the field names defined by this dataset.
valuesanyOPTIONAL. A two dimensional array representing payload records and their values.
$refReference ObjectOPTIONAL. if present, MUST refer to a Dataset using its fully qualified name.