NoDL Concepts

A NoDL document declares a ROS 2 node’s public interface. It can be consumed:

  1. at runtime by conformance testing and health monitoring

  2. at build time by code generators

  3. at documentation time to describe a node for its users

NoDL distinguishes two things:

  • a document — an interface, which may be only part of a node’s interface.

  • a node — a whole node’s interface, composed from documents.

Node identity

A NoDL document does not declare its own name, package, or namespace. Those come from the containing ROS package and the file’s location within it. The document describes interfaces, not identity.

Node interfaces

NoDL defines the interface surface exposed by a ROS 2 node. Those interfaces are:

  • Parameters — typed, with optional default value, description, read-only flag, and validation rules.

  • Topic endpoints: Publishers and subscriptions — name, type, and QoS profile.

  • Service endpoints: servers and clients — name, type, and QoS profile.

  • Action endpoints: servers and clients — name and type.

See the schema reference for field-by-field detail.

Composition: documents into nodes

A single document is often not the whole story: a node inherits interfaces from its ROS base type and may share reusable interfaces with other nodes. A NoDL node composes a whole interface from three layers:

  • base — a built-in ROS 2 node type (node or lifecycle_node) whose interface is inherited. It resolves to a built-in document shipped with nodl_schema (e.g. use_sim_time, and for lifecycle nodes the state-management services and transition event).

  • main — the interface this node’s implementation owns, written in place as a document.

  • mixins — additional documents merged in, each either a reference (nodl://<package>/<name> for a document registered in the ament index, or a path relative to the node file) or an in-place document.

Layers merge in order base → mixins (as listed) → main; later layers win on a name collision, so main always has the final say.

Mixins are single-level: a referenced document is merged as-is and cannot itself declare a base or further mixins. The document schema forbids those keys, so this is enforced, not just convention.

Forward and backward

This split lines up with the two usage models:

  • Working forward (code generation), a generator implements base + main and ignores mixins — mixins describe interfaces owned by other code, not this node’s implementation.

  • Working backward (observation), base can be deduced and the full observed non-base interface placed in main. mixins cannot be deduced and are simply absent; conformance and documentation still work against the merged result.

Syntax & Frontend(s)

The schema is JSON Schema. By default, YAML and JSON files are accepted interchangeably as input; both deserialize to the same document model. Tools should not assume any particular extension (such as .nodl.yaml) or a single frontend.

Validation

NoDL files are validated both at build time (by the ament_nodl CMake macros, before install) and at runtime (by nodl_schema.load_nodl / load_node). Authoring errors surface during the build of the package that owns the file, not at runtime, so a misconfigured node never ships.

The ament_nodl package registers files into the ament index and validates them as it does:

  • ament_nodl_register_node(<exe> FILE ...) registers a node composition (under the nodl_nodes resource type) for an executable.

  • ament_nodl_register_document(<name> FILE ...) registers a reusable document (under nodl_documents) that other nodes pull in as a mixin via nodl://<package>/<name>.

Usage Models

The NoDL project aims to support two directional modes of use for NoDL documents, which it calls “forward” and “backward”.

“NoDL Forward”

When working “NoDL forward”, the document serves as the source of truth that makes a node’s interface exist. The key workflow is:

  1. Write a NoDL definition

  2. Use code generation or dynamic runtime tooling to produce the defined interface

This model is targeted at development of new nodes, or migration of existing ones.

“NoDL Backward”

When working “NoDL backward”, the document is the result of observing an existing node for the purposes of system validation and documentation. The preexisting artifact is the source of truth, and the NoDL Document a reflection of it.

  1. Run existing nodes or inspect their sources

  2. Produce a NoDL description for its interfaces

This model enables drift detection, system analysis, and documentation generation for nodes that are not implemented NoDL-forward.