NoDL Schema reference¶

The following reference is generated from nodl_schema/nodl_schema/schemas/nodl.schema.yaml, which is the canonical source.

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 document¶

json NoDL document : object¶

NoDL Node Definition

NoDL (Node Definition Language) v2 schema.

Describes the public ROS interface of a single ROS 2 node: parameters, publishers, subscriptions, service servers/clients, and action servers/clients. Field names align with rcl_interfaces and rosgraph_msgs (Topic, Service, Action) so a NoDL document 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 document.

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.

A node document 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

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

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"]