Skip to content

MCAP File Format Specification Appendix

This document describes well-known values for MCAP files.

Well-known 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.

Well-known 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

Well-known 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.

jsonschema

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

Well-known 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)

Schema

  • encoding: MUST be either ros2msg or ros2idl