Graph and schema files

Workspaces store graphs in graphs/<name>.yaml and schemas in schemas/<Name>.yaml. Both are YAML.

Graph YAML

The file stem is the graph name — graphs/perception.yaml is the graph perception. Every key the format does not define is a loud parse error, so a typo never becomes a silent default.

There is no policy: block in graph YAML; trigger policy lives only on the macro side. A leftover policy: block fails to parse.

prefix: robot1                    # `graph create` stamps the hostname (".local" stripped) here
multi_publisher_topics:           # optional; absolute topics that may have several publishers
  - /tf
network:                          # optional; restricts the default network exposure
  mode: peer
  egress:
    - /robot1/camera/image
process_groups:                   # optional; usually written by `cerulion graph partition`
  - [camera]
  - [detector]
nodes:
  - id: camera                    # required, unique instance id
    type: camera                  # required, node type = folder name under nodes/
    outputs:                      # optional
      - name: image               # output port name (matches the #[output] field)
        schema: sensor_msgs/Image # optional; "::" is normalized to "/"
        topic: /tf                # optional absolute override of the derived topic name
        max_slice_len: 6291456    # optional
        history_size: 8           # optional, default 0, max 64
  - id: detector
    type: detector
    inputs:                       # optional
      - name: image               # input port name (matches the #[input] field)
        source: camera/image      # relative "<node_id>/<port>", or an absolute "/topic"

Top-level fields

Field	Type	Required	Default	Meaning
`prefix`	String	No	hostname without `.local`, stamped in at create time	Topic prefix for every topic this graph derives. `cerulion graph create` always writes this line, stamping the hostname when you pass no `-n`, so topic names do not change when the file moves to another machine. Only a hand-written file that omits the line takes the same default at load instead.
`nodes`	list	No	empty	The node instances in the graph.
`multi_publisher_topics`	list of absolute topics	No	empty	Opts specific topics out of the single-writer rule, for shared names like `/tf`. Entries must be absolute, well formed, and unique.
`network`	mapping	No	permissive default	Restricts what crosses the machine boundary. See below.
`process_groups`	list of lists of node ids	No	derived	Assigns nodes to worker processes. A hand-written block may split a `block` backpressure edge across groups when the edge is creditable — exactly one in-graph producer and no non-`block` consumers — and the supervisor mints it a cross-process credit word. Two or more in-graph producers, or `block` consumers mixed with non-`block` siblings, are refused before any worker spawns. See Run a graph across processes.
`name`	String	No	ignored	Read and ignored — the file stem is the graph name. Warns when it disagrees with the file name.

Node entry fields

Field	Type	Required	Meaning
`id`	String	Yes	Unique instance id. Becomes part of every topic this instance publishes.
`type`	String	One of the two	Node type — the folder name under `nodes/`.
`ros2`	mapping	One of the two	Declares a stock ROS 2 process instead of a native node. See `ros2:` entries — an entry carries `type:` or `ros2:`, never both and never neither.
`inputs`	list	No	Input bindings. Refused on a `ros2:` entry.
`outputs`	list	No	Output ports. Refused on a `ros2:` entry.

Input fields

Field	Type	Required	Meaning
`name`	String	Yes	Input port name; must match an `#[input]` field on the node type.
`source`	String	Yes	Relative `<node_id>/<port>`, resolved under the graph prefix, or an absolute `/topic`.

An absolute source with no in-graph producer is an external topic: the graph does not own it, other publishers attach freely, and block backpressure is rejected on it.

Output fields

Field	Type	Required	Default	Meaning
`name`	String	Yes		Output port name; must match an `#[output]` field.
`schema`	String	No	inferred from the node source	Schema name. `pkg::Type` is normalized to `pkg/Type`.
`topic`	String	No	derived name	Absolute override, for externally fixed names such as `/tf`. Must be absolute. Other nodes then reference it as `source: /tf`.
`max_slice_len`	usize	No	the schema’s own budget, else 128 MiB with a warning	Maximum payload size for a variable-length schema.
`history_size`	usize	No	`0`	Per-publisher history replayed to late joiners. Maximum 64; a value above a consumer’s `depth` warns at build.

Topic names

Cerulion derives every topic name as /<prefix>/<node_id>/<port>, with a leading slash. With prefix: perception, the sensor instance’s image output publishes to /perception/sensor/image, which is the name topic echo and topic hz expect. Malformed names are rejected at load: a bare /, a trailing /, empty // segments, and a prefix that starts or ends with /.

Graph name limits

The graph name — the file stem — becomes the name of the run’s shared-memory node, so it must be ASCII (an accent or an emoji is refused even though it is valid UTF-8) and at most 119 bytes; 112 bytes if you intend to re-simulate a recording of it, which carries a longer prefix. A name that breaks either rule is refused before the run starts, naming the offending name, the constraint it broke, and the fix:

Error: Transport error: Cannot name the iceoryx2 node 'cerulion_café': an iceoryx2 node name
admits only ASCII below U+0080, and no NUL byte — so an accent, an emoji or any other
non-ASCII character is refused even though it is valid UTF-8. That name is DERIVED from the
graph's identity (its `name:` key, or the file or bag it was loaded from) — rename the graph,
or the bag, and re-run.

Rename graphs/<name>.yaml and re-run. The refusal reaches the runs that use the name verbatim: a single-process graph run, graph profile, and bag play --resim — where a name the recording itself declares makes the bag not replay-grade. A multi-process run, the default on Unix, replaces every character outside [A-Za-z0-9_] with _ when it names its worker processes, so a non-ASCII name runs there; the byte cap still applies.

The `network` block

Cross-machine visibility is on by default for live runs, so this block exists to restrict exposure, not to enable it.

network:
  mode: peer                       # peer | client | disabled (default when the block is absent)
  connect:                         # locators to dial, used verbatim
    - tcp/192.168.1.20:7683
  listen:                          # locators to bind locally
    - tcp/0.0.0.0:7683
  egress:                          # the only topics allowed to leave this machine
    - /robot1/camera/image
  ingress:                         # topics imported from the network
    - /operator/cmd_vel

Field	Meaning
`mode`	`peer` joins the mesh, `client` connects to a router without routing, `disabled` keeps the block inert. An unknown value is rejected and the valid ones listed.
`connect` / `listen`	Locators used verbatim — a declared block adds no scouting, so a two-machine deployment needs one side to `listen` and the other to `connect`.
`egress`	A true allow-list: only these topics ever leave the machine. Each must be produced by an in-graph node.
`ingress`	Topics imported from the network. Each must have no in-graph producer and must be consumed by an in-graph node; frames are schema-checked before they are injected.

Validation rejects, by name: the same topic in both egress and ingress, an egress topic nobody produces, an ingress topic an in-graph node produces, a non-absolute topic in either list, non-empty lists under mode: disabled, and duplicates. Empty lists under peer/client are valid — that is an export-restricted robot. See Network a graph and reach remote robots.

`ros2:` entries

One graph file can describe the whole robot: native Cerulion nodes (type:) beside stock ROS 2 nodes (ros2:), brought up together by cerulion graph run on one transport. A ros2: entry names a ROS 2 process; the run spawns it as a supervised child on the same staged environment cerulion ros2 run uses, so its topics land on the shared transport beside the native nodes’.

nodes:
  - id: detector                  # native, as always
    type: detector
    outputs:
      - name: boxes
        schema: vision_msgs/Detection2DArray

  - id: camera_driver             # a ROS 2 node: `ros2 run <package> <executable>`
    ros2:
      package: usb_cam
      executable: usb_cam_node_exe
      args: ["--log-level", "warn"]        # optional; the executable's own arguments
      params_file: config/usb_cam.yaml     # optional; --ros-args --params-file
      params:                              # optional; --ros-args -p key:=value
        framerate: 30.0
        use_sim_time: false

  - id: bringup                   # or a launch file: `ros2 launch <file> [args]`
    ros2:
      launch: launch/robot.launch.py
      args: ["use_rviz:=false"]            # launch arguments

Key	Meaning
`package` + `executable`	The `ros2 run` form: `ros2 run <package> <executable> [args...]`. Both keys are required together.
`launch`	The `ros2 launch` form: `ros2 launch <file> [args...]`. The alternative to `package`/`executable` — an entry declares one shape or the other, never both. A relative path resolves against the workspace root and must exist; a missing file is refused by name before anything spawns, because `ros2 launch` would otherwise read the name as a package.
`args`	Forwarded verbatim: the executable’s arguments in the `run` form, launch arguments (`name:=value`) in the `launch` form.
`params_file` / `params`	ROS parameters, for the `run` form only — appended as `--ros-args --params-file <file> -p <key>:=<value>`. A launch file carries its own parameters; pass launch arguments through `args`. `params` values must be scalars — a string, a number, or a bool, in declaration order. Put nested parameter trees in a `params_file`.

A ros2: entry is an opaque process the run spawns and supervises. It is not scheduled — no trigger policy, no DAG level, no determinism claim — so level_assignments: and process_groups: may not name one, and cerulion graph levels lists these entries apart from the DAG, which its node count excludes. cerulion graph profile covers native nodes only.

A ros2: entry declares no ports: its topics meet native nodes on the shared transport by name, and the name is the fully-qualified ROS name verbatim — so a native #[input] whose source: is the absolute /tf reads a ROS 2 /tf publisher directly, and the wiring is simply not modelled in the graph. A graph made only of ros2: entries is refused — nothing remains for the runtime to run; use cerulion ros2 launch for a bare launch file. Each entry spawns before the graph starts, on every run shape, in its own process group; the graph process drives teardown with a SIGINT, a 10-second grace for ros2 launch to wind its own nodes down, then a SIGKILL backstop, so no orphan survives an exit path. A child that exits 0 mid-run warns and the graph keeps running — a sidecar finishing must not stop the robot. A child that dies (non-zero, or lost) follows --peer-loss: the default continue warns and runs degraded, and it is not restarted; fail stops the run and exits non-zero naming the entry. A missing librmw_cerulion.so, a missing launch or params file, and ros2 absent from PATH are all refused before anything spawns. graph run --record records a ROS 2 entry’s frames like any other live topic, and the bag’s embedded graph.yaml carries the ros2: entries verbatim, in authored order. cerulion bag info renders them as their own section. cerulion bag play --resim re-executes the native nodes against the recorded frames and skips the entries — one warning names them, --report JSON lists them under ros2_entries_skipped, and ROS 2 is never respawned.

Schema YAML

cerulion schema create <name> writes schemas/<name>.yaml — the name verbatim — holding a skeleton whose single entry key is the PascalCased name. cerulion schema create Detections writes schemas/Detections.yaml. A workspace can also carry ROS message definitions verbatim, as .msg files under schemas/<package>/msg/<Type>.msg; cerulion ros2 attach writes the types it discovered there. That store is a tier between your workspace YAML and the built-in types, and its entries are first-class for graph validate, recording, replay, and schema info — but not for node ports, which refuse a store type because it has no generated Rust type. Declaring one name in both tiers is refused outright, naming every source.

fields: is a mapping, not a list. Each key is the string "<type> <name>" and the value is left empty. A list under fields: still parses as YAML but produces a schema with zero fields and the wrong hash, with no error.

schemas:
  Detections:
    description: "Detector output for one camera frame"
    fields:
      "u32 sequence":
      "f64 confidence":
      "string source":            # variable
      "u8[] payload":             # variable (dynamic array)
      "f64[3] position":          # fixed array
      "Quaternion orientation":   # nested; fixed because Quaternion is recursively fixed

Field types

Type form	Notes
`bool`, `i8`, `u8`, `i16`, `u16`, `i32`, `u32`, `i64`, `u64`, `f32`, `f64`	Primitives — fixed.
`string`	UTF-8 string — variable.
`<T>[N]`	Fixed-size array. Fixed when `T` is fixed.
`<T>[]`	Dynamic array — variable.
`string_fixed[N]`	Fixed-capacity string — fixed.
`<SchemaName>`	Nested schema reference. Fixed when the target is recursively fixed, in which case its layout is inlined into the parent.

A schema is fixed when every field is fixed, and variable otherwise. That distinction decides how a node writes the field (see Messages and schemas) and how the runtime sizes the topic’s shared memory. Inspect the result with cerulion schema info Detections, which prints the field tree, the fixed wire size, the schema hash, and where the definition came from.

Get started

Concepts

Guides

Studio and Hindsight

Reference

Community

Graph YAML

Top-level fields

Node entry fields

Input fields

Output fields

Topic names

Graph name limits

The `network` block

`ros2:` entries

Schema YAML

Field types

​Graph YAML

​Top-level fields

​Node entry fields

​Input fields

​Output fields

​Topic names

​Graph name limits

​The network block

​ros2: entries

​Schema YAML

​Field types

Graph YAML

Top-level fields

Node entry fields

Input fields

Output fields

Topic names

Graph name limits

The `network` block

`ros2:` entries

Schema YAML

Field types