Core Concepts

CBOT protocol has a few core concepts that are briefly explained here.

Message

The CBOT protocol uses a line-based message structure where each line represents a specific command for deserializing the message. Each line contains first a 1-byte long operation code which is then followed by data or other operation codes when needed.

In overall a full CBOT message consists of:

1. Header Section:

2. Data Section:

Key-ID Mapping

Unlike JSON, where each property name is repeated throughout the message, this protocol uses fixed 4-character-long IDs to represent property names. In JSON-like cases, when a new property name is encountered, a new ID is dynamically assigned and used in the rest of the message. This allows the protocol to work without requiring any prior schema/model definition.

Key-ID pairs can also be statically defined beforehand, which removes the need for dynamic mapping, although it does not prohibit the creation of dynamic IDs. This mode is called Untyped Model, which both parties must agree on for the Model to be parsed correctly.

Natively Supported Types

CBOT supports a larger set of native data types that extend beyond JSON's capabilities:

Primitive Types

Date and Time Types

Collection Types

Check details in Supported Types.

Model and Type System

CBOT provides a typed Model system that operates at the protocol level and represents the proper use case for using CBOT. Unlike many other protocols, CBOT actually preserves type information for each object in the Model. This means that polymorphic Model Objects are easy to transport, and collections can contain a mix of different objects without any custom codification.

Depending on the language used, this has different implications. Although the protocol itself always needs concrete types in its model, in Java, for instance, class property types can then be abstract classes or interfaces.

This also means that object structures are validated at the protocol level instead of requiring manual validation.

The protocol also allows only part of the message to be strongly typed, so untyped and typed objects can be mixed at will if both parties are capable of handling the ambiguity.

Namespace

A Namespace is a collection of Model Objects that belong to the same domain. Namespacing is a core concept in CBOT because it needs to know which classes are relevant.

Namespacing can also be used to include or exclude certain groups of types based on their usage. For instance, you might have two CBOT instances: one configured for public and user messages, and the other including admin-type messages as well. This means that when using the user-only API, you wouldn't even be able to attempt to send admin messages.

Model Upgrades

In real life, models rarely stay static and need an upgrade path for new information. In CBOT, this is done through Model Upgrades where older clients can keep using the base model as is, and only clients that are aware of the new features use them. This happens at the protocol level and not in an ad-hoc manner as it would with JSON.

At the current version, upgrades are limited to new properties and new types that are not used in the base model. This allows an upgrade path until the model finally breaks and normally requires new endpoints or other means.

Partial Model Support

If a calling client is in a position where it does not need to support the entire model, it is possible to support it only partially where needed. CBOT has native support for such cases as well.

Encoded Types

CBOT also has a concept of encoded types, where platform-specific types can be encoded into intermediate types, which can then be transported safely in the message. This allows the publishing of semantics through the protocol itself, even though the sender and receiver cannot or do not want to actually agree on what the type means to them.

Use cases include, for instance:

Encoding can be considered symmetric and asymmetric. In symmetric cases, the encoded type is recognized at the protocol level as stated above. In asymmetric encoding, the sender or receiver retains the encoding information.