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.

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)

Schema​

  • encoding: MUST be either ros2msg or ros2idl

Secondary index keys​

The Secondary Index Key name field may contain the following options:

header.stamp​

Indexes the stamp value of the std_msgs/msg/Header-valued header field of the deserialized message data.

  • profile: must be ros1 or ros2

publish_time​

Indexes the publish_time value of Message records.