NoDL Schema reference

NoDL is a family of schemas, all generated below from their canonical sources:

See Concepts for how they relate.

Schema Version

The NoDL schema is JSON Schema Draft 7. This was chosen chosen to trivially support all live ROS 2 distributions - the key limitation being the system packages available on Ubuntu 22.04 Jammy with ROS 2 Humble. After Humble EOL in May 2027, we will consider updating to a newer JSON Schema draft version.

Node composition

A node definition composes a whole interface from a built-in base, the node’s own main interface, and zero or more mixins. main is an interface definition; each mixin is a reference (nodl://<package>/<name> or a relative path) or an in-place interface definition.

json NoDL node definition : object

NoDL Node Definition

A NoDL node definition composes a whole ROS 2 node interface from layers:

  • base – an optional built-in ROS 2 node type whose interface is inherited.

  • main – the interface this node’s implementation owns (an interface definition).

  • mixins – zero or more additional interface definitions merged in by reference or in place.

Code generation works forward from base + main and ignores mixins. Documentation and conformance testing use the fully merged interface (base, then mixins in order, then main; later layers win).

When working backward from an observed node, base can be deduced and the full non-base interface placed in main; mixins cannot be deduced and are simply absent.

Required members:
nodl_version : 2

NoDL schema major version this document targets.

main : Interface

The interface this node’s implementation owns, as an in-place interface definition. Code generation implements exactly this layer.

Optional members:
base : "node" | "lifecycle_node"

Built-in ROS 2 base node type whose interface this node inherits. Resolves to a built-in interface definition shipped with nodl_schema.

mixins : array of string | Interface

Additional interface definitions merged into this node’s interface for documentation and conformance, but ignored by code generation. Each entry is either a reference – an ament-index locator nodl://<package>/<name> or a path relative to this file – or an in-place interface definition (an escape hatch when no registered interface definition exists).

Interface definition

json NoDL interface definition : object

NoDL Interface Definition

NoDL (Node Definition Language) v2 interface definition schema.

Describes a ROS 2 node interface – but not necessarily a whole node’s interface: parameters, publishers, subscriptions, service servers/clients, and action servers/clients. An interface definition may be partial; whole nodes are assembled from interface definitions by the node definition schema (node.schema.yaml) via base + mixins + main. Field names align with rcl_interfaces and rosgraph_msgs (Topic, Service, Action) so an interface definition maps cleanly onto runtime introspection types.

Node identity (name, package, namespace) is established by the enclosing package and the file’s location within it, not declared inside the interface definition.

Required members:
nodl_version : 2

NoDL schema major version this document targets.

Optional members:
description : string

Human-readable description of what this node does.

parameters : object of ParameterDefinition

ROS parameters declared by this node, keyed by parameter name. Parameter shape is borrowed from generate_parameter_library (see parameter.schema.yaml).

publishers : array of TopicEndpoint

Topic publishers exposed by this node.

subscriptions : array of TopicEndpoint

Topic subscriptions consumed by this node.

service_servers : array of ServiceEndpoint

Service servers exposed by this node.

service_clients : array of ServiceEndpoint

Service clients used by this node.

action_servers : array of ActionEndpoint

Action servers exposed by this node.

action_clients : array of ActionEndpoint

Action clients used by this node.

An interface definition references these shared types (generated from the schema’s definitions, see nodl/doc/conf.py):

json RosName : string

Name of a ROS graph resource (Node, Topic, Service, Action). Accepts the standard name forms – absolute (/foo/bar), relative (foo/bar), and private (~/foo). Must start with /, ~, or a letter; may contain letters, digits, _, /; and must end with a letter, digit, or _ (not a slash). See https://design.ros2.org/articles/topic_and_service_names.html for more information on names.

json RosType : string

ROS interface type, format package/(msg|srv|action)?/TypeName. Middle namespace is optional and may be determined by usage context (e.g. a publisher type implies msg).

Example

"std_msgs/msg/String"

Example

"std_msgs/String"

Example

"geometry_msgs/msg/Twist"

Example

"std_srvs/srv/Trigger"

Example

"lifecycle_msgs/srv/ChangeState"

Example

"example_interfaces/action/Fibonacci"

Example

"nav2_msgs/action/NavigateToPose"
json QosProfile : object

QoS profile settings. Mirrors rcl_interfaces/QoSProfile field set and naming, but uses string enums in place of RMW integer codes for readability and signed-int nanoseconds in place of builtin_interfaces/Duration for ergonomics – codegen converts the int to a Duration. UNKNOWN values from the RMW spec are excluded; they are only meaningful for runtime observation.

Required members:
history : "KEEP_LAST" | "KEEP_ALL" | "SYSTEM_DEFAULT"

History policy.

reliability : "RELIABLE" | "BEST_EFFORT" | "SYSTEM_DEFAULT" | "BEST_AVAILABLE"

Reliability policy.

Optional members:
depth : integer[1, +∞)

Queue depth. Required when history is KEEP_LAST.

durability : "TRANSIENT_LOCAL" | "VOLATILE" | "SYSTEM_DEFAULT" | "BEST_AVAILABLE"

Durability policy.

deadline_ns : integer[0, +∞)

Deadline between successive messages, in nanoseconds. Zero means no deadline is enforced. Stored as a signed 64-bit integer (~292 years range).

lifespan_ns : integer[0, +∞)

Maximum age of a message before it is dropped, in nanoseconds. Zero means messages never expire.

liveliness : "AUTOMATIC" | "MANUAL_BY_TOPIC" | "SYSTEM_DEFAULT" | "BEST_AVAILABLE"

Liveliness policy.

liveliness_lease_duration_ns : integer[0, +∞)

Maximum time between liveliness assertions before the publisher is considered not alive, in nanoseconds. Zero means the lease never expires.

json TopicEndpoint : object

Topic endpoint – same shape for publishers and subscriptions; direction is implied by which top-level array contains it.

Required members:
name : RosName

Topic name.

type : RosType
qos : QosProfile
Optional members:
description : string
json ServiceEndpoint : object

Service endpoint – same shape for servers and clients; direction is implied by which top-level array contains it. A single qos profile applies; create_service accepts only one QoS input and applies it to both the request and response sides at runtime.

Required members:
name : RosName

Service name.

type : RosType
Optional members:
qos : QosProfile
description : string
json ActionEndpoint : object

Action endpoint – same shape for servers and clients; direction is implied by which top-level array contains it. The underlying decomposition into goal/result/cancel services and feedback/status topics (per rcl_interfaces/Action) is not modelled here; it is an implementation concern.

Required members:
name : RosName

Action name.

type : RosType
Optional members:
description : string

Parameter schema

Parameters reference the subschema nodl_schema/nodl_schema/schemas/parameter.schema.yaml. This is a formalization of the implicit schema defined by generate_parameter_library - NoDL builds on that work rather than reinventing the wheel.

json ParameterDefinition : object
Required members:
type : ParameterType
Optional members:
default_value : DefaultValue
description : string = ""

Human-readable description displayed by ros2 param describe

read_only : boolean = false

If true, parameter can only be set at launch, not dynamically

additional_constraints : string = ""

Custom constraint metadata (e.g., JSON schema) - not validated by the library

validation : Validation
json ParameterType : ScalarType | ArrayType | FixedSizeType

The parameter data type

json ScalarType : "bool" | "int" | "double" | "string" | "none"

Scalar types: - bool: C++ bool, Python bool - int: C++ int64_t, Python int - double: C++ double, Python float - string: C++ std::string, Python str - none: No code generated (used for structure-only nodes)

json ArrayType : "bool_array" | "int_array" | "double_array" | "string_array"

Array types: - bool_array: C++ std::vector<bool>, Python [bool] - int_array: C++ std::vector<int64_t>, Python [int] - double_array: C++ std::vector<double>, Python [float] - string_array: C++ std::vector<std::string>, Python [str]

json FixedSizeType : string

Fixed-size types with pattern <base_type>_fixed_<size>: - string_fixed_XX: C++ rsl::StaticString<XX>, Python str (max XX chars) - int_array_fixed_XX: C++ rsl::StaticVector<int64_t, XX>, Python [int] (max XX elements) - double_array_fixed_XX: C++ rsl::StaticVector<double, XX>, Python [float] (max XX elements) - string_array_fixed_XX: C++ rsl::StaticVector<std::string, XX>, Python [str] (max XX elements)

Note: bool_array_fixed is NOT supported. Fixed-size types automatically get a size_lt<> validator with value size+1.

Example

"string_fixed_25"

Example

"int_array_fixed_5"

Example

"double_array_fixed_10"

Example

"string_array_fixed_3"
json DefaultValue

Initial value for the parameter. Type must match the declared parameter type. If omitted, the parameter becomes required at initialization. Supports: bool, int, double (including NaN, Inf, scientific notation), string, and arrays of these types.

json Validation : object

Dictionary of validation function names and their arguments. Validators can be specified with or without the <> suffix (both are equivalent). For example: bounds<>: [0, 100] is the same as bounds: [0, 100]

Optional members:
bounds : BoundsValidator
lt : ComparisonValidator
gt : ComparisonValidator
lt_eq : ComparisonValidator
gt_eq : ComparisonValidator
one_of : OneOfValidator
not_empty : NoArgValidator
fixed_size : SizeValidator
size_gt : SizeValidator
size_lt : SizeValidator
unique : NoArgValidator
subset_of : SubsetOfValidator
element_bounds : BoundsValidator
lower_element_bounds : ComparisonValidator
upper_element_bounds : ComparisonValidator
json BoundsValidator : array[2] of number

Inclusive bounds checking: [lower, upper]

Example

[0, 100]

Example

[0.0, 1.0]

Example

[-1.0, 1.0]
json ComparisonValidator : array[1] of number | number

Single value comparison: [value] or bare value

One of:
array[1] of number
number

Can also be specified as a bare number

Example

[0]

Example

[100]

Example

[0.001]

Example

15

Example

0.5
json SizeValidator : array[1] of integer[0, +∞) | integer[0, +∞)

Size/length constraint: [length]

One of:
array[1] of integer[0, +∞)
integer[0, +∞)

Can also be specified as a bare integer

Example

[6]

Example

[10]

Example

6
json OneOfValidator : array[1] of array[1..]

Parameter must be one of the specified values: [[val1, val2, ...]]

Example

[["spline", "linear"]]

Example

[[0, 1, 2, -1]]

Example

[[true, false]]
json SubsetOfValidator : array[1] of array[1..]

All array elements must be in the specified set: [[val1, val2, ...]]

Example

[["x", "y", "z"]]

Example

[[1, 2, 3, 4, 5]]
json NoArgValidator : null | array[..0]

Validator that takes no arguments

Example

null

Example

[]
json CustomValidator : null | array | number | string | boolean

Custom validator with namespace-qualified function name. The function must: - Accept rclcpp::Parameter const& as first argument - Accept additional arguments matching the YAML specification - Return tl::expected<void, std::string> type - Be defined in a header file passed to the code generator

Example

null

Example

[1.0, 2.0]

Example

["arg1", "arg2"]