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:
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:
- Tags MUST be limited to those allowed by the JSON Schema ruleset.
- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
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.
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 Name | Type | Format | Comments |
---|---|---|---|
integer | integer | int32 | signed 32 bits |
long | integer | int64 | signed 64 bits |
float | number | float | |
double | number | double | |
string | string | ||
byte | string | byte | base64 encoded characters |
binary | string | binary | any sequence of octets |
boolean | boolean | ||
date | string | date | As defined by full-date - RFC3339 |
dateTime | string | date-time | As defined by date-time - RFC3339 |
object | object | embedded/nested object | |
array | array | A valid type | embedded/nested array |
Examples
An integer
A double
A base64 encoded binary
A date-time string
Embedded object
Embedded array of numbers
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 Name | Type | Description |
---|---|---|
camel | string | REQUIRED. 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. |
name | string | REQUIRED. The fully qualified name of the resource. |
title | string | OPTIONAL. The human friendly name given to a resource. |
description | string | OPTIONAL. A free-text account of a resource. MAY include rich text. MAY be a reference to external documentation using a URL Reference Object. |
tags | Tag Object | OPTIONAL. 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:
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
Property Value Object
The property value object is used to set a property.
Property Value Object: Fixed Fields
Field Name | Type | Description |
---|---|---|
name | string | The property name. |
value | any | The 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 Name | Type | Description |
---|---|---|
label | string | The tag label. |
value | string | The 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
Embedded objects and arrays example: News Article
Parameter Object: Fixed Fields
Field Name | Type | Description |
---|---|---|
name | string | REQUIRED. The unique name of the parameter. The name SHOULD be a code friendly identifier. |
title | string | OPTIONAL. See Resource Title. |
description | string | OPTIONAL. See Resource Description. |
type | string | REQUIRED. One of the six valid types allowed by CAMEL: integer, number, boolean, string, object, array. |
format | string | OPTIONAL. A descriptive format string like date , email , or double . See Data Types for a discussion of the built-in formats. |
required | boolean | OPTIONAL. 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:
Schema reference, used in parameter declarations:
Reference Object: Fixed Fields
Field Name | Type | Description |
---|---|---|
$ref | string | REQUIRED. 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
URL Reference Object: Fixed Fields
Field Name | Type | Description |
---|---|---|
$url | string | REQUIRED. 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:
Skill Object: Fixed Fields
Field Name | Type | Description |
---|---|---|
camel | string | REQUIRED. See CAMEL Specification Version. |
name | string | REQUIRED. See Resource Name. |
title | string | REQUIRED. See Resource Title. |
description | string | OPTIONAL. See Resource Description. |
tags | Tag Object | OPTIONAL. See Resource Tags. |
properties | Property Object | OPTIONAL. |
inputs | Skill Input Object | REQUIRED. An array of Input Objects. At least one Input is required. |
outputs | Skill Output Object | OPTIONAL. An array of Output Objects. |
datasets | Dataset Reference Object | OPTIONAL. 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 Name | Type | Description |
---|---|---|
name | string | REQUIRED. |
title | string | REQUIRED. |
parameters | Parameter Object| Reference Object | REQUIRED. |
routing | Routing Object | REQUIRED. |
Skill Output Object
This object defines an output message used by the Skill.
Skill Output Object: Fixed fields
Field Name | Type | Description |
---|---|---|
name | string | REQUIRED. |
title | string | REQUIRED. |
parameters | Parameter Object | Reference Object | REQUIRED. |
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.
Property based routing
Field based routing
All Routing: Fixed fields
Field Name | Type | Description |
---|---|---|
action | string | REQUIRED. The Resource Name of the action to route to. |
runtime | string | OPTIONAL. The Resource Name of the action runtime to use. The default runtime is assumed if not provided. |
output | string | REQUIRED. The name of the Output to route to. |
Property Routing: Fixed fields
Field Name | Type | Description |
---|---|---|
property | string | REQUIRED. The name of the property to apply routing rules to. |
default | All Routing | OPTIONAL. The default routing rule used if no property matches are made. |
rules | Routing Rule Object | REQUIRED. List of routing rules to apply to the specified property value. |
Field Routing: Fixed fields
Field Name | Type | Description |
---|---|---|
field | string | REQUIRED. The name of the Message field to apply routing rules to. |
default | All Routing | OPTIONAL. The default routing rule used if no property matches are made. |
rules | Routing Rule Object | REQUIRED. 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 Name | Type | Description |
---|---|---|
match | string | The value to match. |
action | string | REQUIRED. The Resource Name of the action to route to. |
runtime | string | OPTIONAL. The Resource Name of the action runtime to use. The default runtime is assumed if not provided. |
output | string | REQUIRED. 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 Name | Type | Description |
---|---|---|
name | string | REQUIRED. The name of the reference. |
title | string | OPTIONAL. A human friendly display name for the reference. |
description | string | OPTIONAL. A description or documentation of the reference. |
parameters | Parameter Object| Reference Object | OPTIONAL. The fields expected in the dataset. |
requiresWrite | boolean | OPTIONAL. 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:
OR
Dataset Object: Fixed Fields
Field Name | Type | Description |
---|---|---|
camel | string | REQUIRED. See CAMEL Specification Version |
name | string | REQUIRED. See Resource Name. |
title | string | REQUIRED. See Resource Title. |
description | string | OPTIONAL. See Resource Description. |
tags | Tag Object | OPTIONAL. See Resource Tags. |
parameters | Parameters Object | REQUIRED. Defines the fields included in this dataset. The dataset MAY include additional fields not defined here. |
connections | Connection Configuration Object | REQUIRED. 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 Name | Type | Description |
---|---|---|
default | Connection Reference Object | OPTIONAL. The default connection to use in environments where no environment specific connection configuration exists. |
environments | Connnection Reference Object | OPTIONAL. 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 Name | Type | Description |
---|---|---|
name | string | REQUIRED. The fully qualified name of the connection to use. |
type | string | REQUIRED. The name of the connection type. |
query | Property Value | OPTIONAL. Defines the default connection query parameters to use when reading from this connection. The definitions of these properties is provided by connection type object. |
environment | string | OPTIONAL. |
Message Object
This object defines the message format used for skill-to-skill and agent-to-skill communication.
Message Object: Fixed fields
Field Name | Type | Description |
---|---|---|
payload | Payload Object | REQUIRED. |
parameters | Parameter Object | OPTIONAL. |
Payload Object
This object is used in Messages to carry a payload sent for processing. Payloads have four different styles demonstrated in examples below:
- Inline Objects
- Inline Records
- Inline DataFrame
- DataSet Reference (e.g. pass-by-reference)
Payload Object: Examples
Payload with Inline Object
Payload with Inline Records
Payload with Inline DataFrame
Payload with DataSet Reference
Payload Object: Fixed fields
Field Name | Type | Description |
---|---|---|
records | any | OPTIONAL. An array of JSON objects representing dataset records. The fields of the these records MUST match the fields defined in the dataset. |
columns | string | OPTIONAL. 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. |
values | any | OPTIONAL. A two dimensional array representing payload records and their values. |
$ref | Reference Object | OPTIONAL. if present, MUST refer to a Dataset using its fully qualified name. |