NoDL
One reviewable interface file per ROS 2 node, generating its code, docs and drift checks
License
Apache-2.0
Overview
NoDL, the Node Definition Language, lets a ROS 2 node declare its interface — publishers, subscriptions, services, actions, QoS and parameters — in a single document that can be reviewed like any other contract. From that document it generates the node's wiring as a C++ abstract base class or an rclpy base class, leaving the behaviour hand-written; renders an exact interface reference through a rosdoc2 Sphinx extension; and checks a running system for drift against it. The reverse direction works too: ros2 nodl describe observes a live node and drafts its NoDL, so an existing codebase can adopt it without a rewrite. It is developed by the ROS 2 ROSGraph Working Group under ros-tooling and released for every current ROS 2 distribution.
A ROS 2 node's interface lives nowhere in particular. Topics and services are created in constructor code, parameters are declared wherever someone remembered to, QoS is a detail of a call site, and the only complete description of what a node exposes is the running graph. NoDL puts that interface in one file and makes the file authoritative. The authors are careful about the scope: it checks graph contracts — endpoints, types, QoS, parameters — and says plainly that it does not prove behaviour, TF frame semantics, scheduling or real-time guarantees.
The same document serves three uses that can be adopted separately. Generation writes the plumbing: the C++ generator emits an abstract base class with every endpoint wired and delegates parameters to generate_parameter_library, and the Python generator does the same for rclpy, including lifecycle nodes. Documentation renders an interface reference from the file rather than from comments that drift. Conformance compares the declared contract against what a running node actually exposes, and ros2 nodl diff compares two documents offline. ament_nodl registers documents with the ament index and runs the live-node check under colcon test.
The project began in 2020 and version 2 landed in September 2026 after a burst of work: nested parameters, Python service, action and lifecycle generation, and a runnable dummy-robot tutorial all merged in the fortnight before release. Its progress is reported in the ROS PMC's own minutes, and version 2.1 is scheduled for the next ROS 2 distribution in April 2027.
Why it matters
Interface wiring is where a lot of ROS 2 time goes and where a lot of integration bugs live: a topic name that changed in one node and not its consumer, a parameter nobody documented, a QoS mismatch that only shows at runtime. NoDL is the ROS project's own attempt to make the node interface an explicit contract instead of an emergent property of the code, from the working group responsible for the ROS graph tooling. That provenance is why it is worth watching even this early: if it takes, it is the kind of thing that ends up in every template.
Problem it solves
A ROS 2 node's interface is scattered through constructor code and only fully visible in the running graph, so it goes undocumented and drifts between nodes. NoDL makes it a single reviewed file that generates the wiring, generates the documentation, and catches a running system that no longer matches it.
Key takeaways
- One NoDL document declares a node's publishers, subscriptions, services, actions, QoS and parameters
- Generates the interface wiring as a C++ abstract base class or an rclpy base class, leaving behaviour hand-written
- Renders an exact interface reference into ROS documentation through a rosdoc2 Sphinx extension
- Checks a running node against its declared contract, and ros2 nodl diff compares documents offline
- ros2 nodl describe drafts a NoDL from a live node, so existing code can adopt it without a rewrite
- Developed by the ROS 2 ROSGraph Working Group and released for Humble, Jazzy, Kilted, Lyrical and Rolling
- Version 2 shipped in September 2026; 2.1 is planned for the April 2027 ROS 2 distribution
Who it is for
- ROS 2 teams whose integration bugs come from nodes disagreeing about topics, types, QoS or parameters
- Package maintainers who want interface documentation generated rather than hand-kept
- Anyone starting a new node who would rather declare its interface once than write the plumbing by hand
- CI owners who want a colcon test that fails when a running node drifts from its contract
Limitations
- Early adoption stage by its own description — v2 is out and the schema is called reasonably stable, not settled
- Checks the graph contract only; it does not prove behaviour, TF frame semantics, scheduling or real-time properties
- Code generation covers C++ and Python; there is no generator for other client libraries
- Some full-test dependencies are pip-only, so the buildfarm builds run a reduced test suite
- Adopting generation means your node inherits from a generated base class, a structural change for existing code
- Small maintainer group — most of the recent work comes from a handful of contributors