Skip to main content

MCAP Format Registry

This document describes well-known values for MCAP files.

Compression formats​

The Chunk compression field may contain the following options:

  • lz4: an algorithm that prioritizes compression/decompression speed over compression ratio.
  • zstd: an algorithm with a tunable compression ratio/speed tradeoff.

Message encodings​

The Channel message_encoding field describes the encoding for all messages within a channel. This field is mandatory.

ros1​

  • message_encoding: ros1

cdr​

  • message_encoding: cdr (used in ROS 2)

protobuf​

flatbuffer​

cbor​

  • message_encoding: cbor

json​

  • message_encoding: json

Schema encodings​

The Schema encoding field describes the encoding of a Channel's schema. Typically, this is related to the Channel's message_encoding, but they are separate concepts (e.g. there are multiple schema languages for json).

This field is required for some message encodings (e.g. protobuf) and optional for others (e.g. json).

(empty string)​

Schema encoding may only be omitted for self-describing message encodings such as json.

  • name: May contain any value
  • encoding: (empty string)
  • data: Must be empty (0 bytes)

protobuf​

  • name: Fully qualified name to the message within the descriptor set. For example, in a proto file containing package foo.bar; message Baz {} the fully qualified message name is foo.bar.Baz.
  • encoding: protobuf
  • data: A binary FileDescriptorSet as produced by protoc --descriptor_set_out.

flatbuffer​

  • name: Fully qualified name corresponding to a name in the reflection Object table. For example in a schema containing namespace foo; table Bar {} the fully qualified name is foo.Bar.
  • encoding: flatbuffer
  • data: A reflection.Schema flatbuffer describing the parsed schema encoded as a binary flatbuffer. This can be generated by running flatc -b --schema on the fbs file.

ros1msg​

  • name: A valid package resource name, e.g. sensor_msgs/PointCloud2.
  • encoding: ros1msg
  • data: Delimited concatenated ROS1 .msg files.

ros1msg Data Format​

the data field contains the concatenated .msg file content that is sent in the ROS subscription connection header for this message type.

The top-level message definition is present first, with no delimiter. All dependent .msg definitions are preceded by a two-line delimiter:

  • One line containing exactly 80 = characters
  • One line containing MSG: <package resource name> for that type. The space between MSG: and the package resource name is mandatory. The package resource name does not include a file extension.

This format can be reproduced using gendeps --cat.

ros2msg​

  • name: A valid package resource name, e.g. sensor_msgs/msg/PointCloud2.
  • encoding: ros2msg
  • data: Delimited concatenated ROS2 .msg files

ros2msg Data Format​

The .msg definition is stored alongside its dependencies in the same format as ros1msg.

ros2idl​

  • name: A valid package resource name, e.g. sensor_msgs/msg/PointCloud2
  • encoding: ros2idl
  • data: Delimited concatenated ROS2 .idl files

ros2idl Data Format​

The IDL definition of the type specified by name along with all dependent types are stored together. The IDL definitions can be stored in any order. Every definition is preceded by a two-line delimiter:

  • a line containing exactly 80 = characters, then
  • A line containing only IDL: <package resource name> for that definition. The space between IDL: and the package resource name is mandatory. The package resource name does not include a file extension.

omgidl​

The omgidl schema encoding stores OMG IDL definitions for (X)CDR-encoded messages.

  • name: The globally-scoped name of the message type, eg. top_level_module::my_module::MyType
  • encoding: omgidl
  • data: valid OMG IDL definition file contents with a definition for the message type and all referenced types.

Producing schema.data for the omgidl schema encoding​

Most commonly, IDL definitions for separate types are stored in separate files, and use C++ preprocessor #include statements to include definitions for types referenced in that definition.

For the omgidl schema encoding, the data field needs to contain all of those definitions. In other words, the data field should read as a single source file containing definitions for the message type and all referenced types.

One way to produce this is to use a C++ compiler to resolve those #include directives:

# Run from the root of your IDL definition tree, or use additional `-I` arguments to indicate your
# full include path to the compiler.
# The `gcc` output may contain debugging lines such as "# 1 "top_level_module/my_module/MyType.idl",
# the grep command here is intended to filter those out.
$ gcc -E -I. top_level_module/my_module/MyType.idl | grep -v "^# \d" > all_definitions.idl

For the following files:

top_level_module/my_module/MyType.idl
#include "top_level_module/other_module/OtherType.idl"

module top_level_module {
  module my_module {
    struct MyType {
      top_level_module::other_module::OtherType val;
    }
  }
}
top_level_module/other_module/OtherType.idl
module top_level_module {
  module other_module {
    struct OtherType {
      float val;
    }
  }
}

This should produce:

schema.data
module top_level_module {
  module other_module {
    struct OtherType {
      float val;
    }
  }
}

module top_level_module {
  module my_module {
    struct MyType {
      top_level_module::other_module::OtherType val;
    }
  }
}

For this example, schema.name should be set to top_level_module::my_module::MyType.

jsonschema​

  • name: May contain any value
  • encoding: jsonschema
  • data: JSON Schema

Profiles​

ROS1​

The ros1 profile describes how to create MCAP files for ROS 1.

  • profile: MUST be ros1

Channel​

  • message_encoding: MUST be ros1
  • metadata keys:
    • callerid (optional, string)
    • latching (optional, bool stringified as "true" or "false")

Schema​

  • encoding: MUST be ros1msg

ROS2​

The ros2 profile describes how to create MCAP files for ROS 2.

Header​

  • profile: MUST be ros2

Channel​

  • message_encoding: MUST be cdr

  • metadata:

    • offered_qos_profiles (required, string) YAML formatted sequence of QoS policy values. See ROS QoS Policies for Recording docs for more details. The policy value may change depending on the ROS distro. Below is an example for a single policy schema value.
    history: [keep_all, keep_last]
    depth: int
    reliability: [system_default, reliable, best_effort, unknown]
    durability: [system_default, transient_local, volatile, unknown]
    deadline:
      sec: int
      nsec: int
    lifespan:
      sec: int
      nsec: int
    liveliness: [system_default, automatic, manual_by_topic, unknown]
    liveliness_lease_duration:
      sec: int
      nsec: int
    avoid_ros_namespace_conventions: [true, false]

Schema​

  • encoding: MUST be either ros2msg or ros2idl