[Feature Request] Standalone validator tool

[Nitschi]

Summary

Add a CLI tool (e.g. generate_parameter_library_validate) that validates a ROS 2 parameter config YAML against one or more parameter definition YAMLs, without requiring a ROS 2 runtime, a colcon build, or a running node.

Motivation

Currently, the only way to validate whether a config YAML conforms to the parameter definitions is to build the generated code, launch a node with --params-file, and observe whether it throws. This works during development, but creates pain in two important scenarios:

CI pipelines: A robotics project may have dozens of parameter definition YAMLs across packages and a large monolithic (or composed) config YAML that is deployed to the robot. When someone changes a parameter value in that config, the only feedback loop today is a full colcon build + node launch. A lightweight validation step in CI (similar to a linter) would catch issues like typos in parameter names, wrong types, or out-of-bounds values in seconds rather than minutes.

Field engineers and integrators: People who configure robots on-site often do not have a full build environment. They edit YAML config files and deploy them. A wrong parameter name or an out-of-range value currently only surfaces as a runtime crash or cryptic error message on the robot. A standalone validation tool that they can run on their laptop (with just a pip install) would save significant debugging time and prevent deploying broken configs to production robots.

The library already has generate_parameter_library_markdown as a precedent for a standalone tool that reads the parameter definition YAML and produces useful output without requiring ROS 2. A validator would follow the same pattern.

Proposed interface

# Validate a single config against a single parameter definition
generate_parameter_library_validate \
  --param-definition src/my_package/config/my_parameters.yaml \
  --config config/robot.yaml

# Validate against multiple parameter definitions (common for composed systems)
generate_parameter_library_validate \
  --param-definition src/pkg_a/config/a_parameters.yaml \
  --param-definition src/pkg_b/config/b_parameters.yaml \
  --config config/robot.yaml

# Strict mode: also warn about parameters in the config
# that do not appear in any definition (catches typos)
generate_parameter_library_validate \
  --param-definition src/my_package/config/my_parameters.yaml \
  --config config/robot.yaml \
  --strict

Exit code 0 on success, non-zero on validation failure, with human-readable error messages:

ERROR: my_node.background.r: value 300 violates bounds<>[0, 255]
ERROR: my_node.background.colour: unknown parameter (did you mean 'color'?)
ERROR: my_node.pid.rate: expected type 'double', got 'string' ("fast")
WARNING: my_node.background.b: missing from config, will use default_value 0

Scope of validation

The parameter definition YAML format already encodes rich type and constraint information. The following built-in validators all map cleanly to static checks that can be performed without a ROS 2 runtime:

Value validators: bounds<>, lt<>, gt<>, lt_eq<>, gt_eq<>, one_of<>

String validators: fixed_size<>, size_gt<>, size_lt<>, not_empty<>, one_of<>

Array validators: unique<>, subset_of<>, fixed_size<>, size_gt<>, size_lt<>, not_empty<>, element_bounds<>, lower_element_bounds<>, upper_element_bounds<>

The tool should also check:

• Type correctness (e.g. int vs double vs string vs arrays)
• Required parameters (parameters without default_value must be present in the config)
• Namespace structure (the ros__parameters nesting in config YAMLs)
• Mapped parameters (__map_<key> where possible, i.e. when the key parameter has a default_value or is present in the config)

Explicitly out of scope (with warning):

• Custom C++ validator functions (e.g. "my_project::integer_equal_value": [3]). These are arbitrary code and cannot be evaluated offline. The tool should emit a warning: INFO: my_node.param: custom validator 'my_project::integer_equal_value' cannot be checked offline, skipped
• read_only is a runtime behavioral constraint, not checkable offline

Implementation considerations

• The tool should be a pure Python CLI with no dependency on ROS 2 packages, so it can be installed via pip in any environment. This matches how generate_parameter_library_markdown works.
• The existing YAML parsing logic in generate_parameter_library_py.parse_yaml already understands the full parameter definition DSL and could be reused as the foundation.
• The config YAML parser needs to handle the ros__parameters namespace and the /** or node-specific namespacing conventions.
• Consider also supporting a --output-json-schema flag that converts the parameter definitions to JSON Schema. This would enable integration with existing JSON Schema tooling and IDE support (e.g. YAML language server in VS Code for autocompletion and inline validation of config files).

Example CI usage

# GitHub Actions example
- name: Validate robot config
  run: |
    pip install generate_parameter_library
    generate_parameter_library_validate \
      --param-definition src/navigation/config/nav_parameters.yaml \
      --param-definition src/behavior/config/behavior_parameters.yaml \
      --config deploy/config/robot_production.yaml \
      --strict

Related

• generate_parameter_library_markdown already demonstrates the pattern of a standalone CLI tool that processes parameter definition YAMLs
• Issue Potentially misleading error messages in the library #59 reports confusing runtime error messages for invalid configs, which offline validation would help prevent
• Issue Separate C++ interface library for parameter validation. #30 discusses separating validation logic, which aligns with making validation available outside of generated code

[christophfroehlich]

I support this idea!

[emersonknapp]

This one's been on my radar, too. I believe that providing a usable schema solves 90% of the problem, at that point a dedicated tool maybe isn't even necessary.

In the ROSGraph Working Group we've been making progress on getting the NoDL project going, which is right now looking at integrating generate_parameter_library as the implementation for the parameter portion of overall node boilerplate generation.

See ros-tooling/nodl#50 which is tracking work toward a NoDL schema v2, which will be at least partially based on the cake schema, which has explicitly encoded the generate_parameter_library implicit schema into JSONschema to use for the parameters: portion of a node definition.

There's a slightly larger conversation I'd like to have of how/if generate_parameter_library should be intertwined with the NoDL work as it goes forward. Maybe for starters generate_parameter_library could consume just the NoDL schema for use in validating inputs. Once it's released.