[Draft]Add structured parameter support by rahul-k-a · Pull Request #2944 · ros2/rclcpp

rahul-k-a · 2025-08-30T13:33:09Z

Description

Adds additional API that allows the user to access structured YAML parameters as a YAML::Node (part of yaml-cpp in rclcpp. Original GSOC proposal can be found here
Essentially, given a parameter YAML file such as

<node>:
  ros__parameters:
    passenger_size:
      min:
        x: 0.6
        y: 0.4
        z: 0.17
      max:
        x: 0.850
        y: 0.65
        z: 0.47

In the code, the user can declare a structured yaml parameter as

this->declare_parameter("passenger_size", YAML::Node(""));

And get access to all the elements under passenger_size as

YAML::Node passenger_size = this->get_parameter("passenger_size").as_yaml();

They can then access individual fields using the standard dict() syntax

double max_x = passenger_size['max']['x'];
double_min_x = passenger_size['min']['x'];

Users can also now set yaml parameters through the ros2 CLI. The syntax is very similar to the one already used for setting messages. For example:

ros2 param set <node> passenger_size "{min: {x : 0.1, y: 0.2, z: 0.3}, max: [1, 2, "hello"] }"

will change passenger size as

min:
  x: 0.1
  y: 0.2
  z: 0.3
max:
  - 1
  - 2
  - hello

Fixes # (issue)

Is this user-facing behavior change?

Yes, it adds an additional parameter type that they can use. None of the existing parameter types are affected. Support for existing namespaced parameters is not affected. If required users will still be able to access individual namespaced parameters such as passenger_size.min.x, passenger_size.max.x, etc.

Did you use Generative AI?

No.

Additional Information

Companion rclpy PR: [Draft]Add structured parameter support rclpy#1494
Companion rcl PR: [Draft]Add structured parameter support rcl#1254
Compantion rcl_interfaces PR: Add structured parameter support rcl_interfaces#183

Signed-off-by: Rahul K.A <karahul209@gmail.com>

rahul-k-a · 2025-08-30T13:44:42Z

Tagging this as a draft, because Im yet to add in tests/ apply linter. Once done,will remove the draft tag. Maintainers are welcome to start reviewing it in the meantime

rahul-k-a · 2025-08-30T13:54:00Z

Tagging this as a draft, because Im yet to add in tests/ apply linter. Once done,will remove the draft tag. Maintainers are welcome to start reviewing it in the meantime

alsora · 2025-09-06T09:05:21Z

CI for all the PRs involved

Linux
Linux-aarch64
Linux-rhel
Windows

ahcorde

uncrustify is failing. You might need to run

ament_uncrustify --reformat <filenames or directory>

ahcorde · 2025-09-08T16:19:44Z

rclcpp/include/rclcpp/parameter.hpp

+  as_yaml() const;
+
+


Suggested change

as_yaml() const;

as_yaml() const;

ahcorde · 2025-09-08T16:20:09Z

rclcpp/include/rclcpp/parameter_value.hpp

  explicit ParameterValue(const std::vector<std::string> & string_array_value);

+
+  /// Generate a parameter value with type PARAMETER_YAML


Suggested change

explicit ParameterValue(const std::vector<std::string> & string_array_value);

/// Generate a parameter value with type PARAMETER_YAML

explicit ParameterValue(const std::vector<std::string> & string_array_value);

/// Generate a parameter value with type PARAMETER_YAML

ahcorde · 2025-09-08T16:20:48Z

rclcpp/include/rclcpp/parameter_value.hpp


+  template<ParameterType type>
+  constexpr
+  typename std::enable_if<type == ParameterType::PARAMETER_YAML, const YAML::Node>::type


include <type_traits>

ahcorde · 2025-09-08T16:21:33Z

rclcpp/package.xml

 <package format="2">
  <name>rclcpp</name>
-  <version>30.1.0</version>
+  <version>30.0.0</version>


don't change this number manually. Restore

ahcorde · 2025-09-08T16:21:47Z

rclcpp/src/rclcpp/node_interfaces/node_parameters.cpp

 }

+


Suggested change

}

}

ahcorde · 2025-09-08T16:22:22Z

rclcpp/src/rclcpp/node_interfaces/node_parameters.cpp

 #include <string>
 #include <utility>
 #include <vector>
+#include "yaml-cpp/yaml.h"


move above <rcl_yaml_param_parser/parser.h> and use <>

ahcorde · 2025-09-08T16:23:05Z

rclcpp/src/rclcpp/node_interfaces/node_parameters.cpp

+}
+
+
+RCLCPP_LOCAL


Suggested change

}

RCLCPP_LOCAL

}

RCLCPP_LOCAL

ahcorde · 2025-09-08T16:23:46Z

rclcpp/src/rclcpp/node_interfaces/node_parameters.cpp

+
+RCLCPP_LOCAL
+/// Pulled from Question 78243576 from Stack Overflow 
+void __traverse_node_and_change_value(YAML::Node & root, const std::vector<std::string>& path, rclcpp::ParameterValue value)


lines < 100 characters

asherikov · 2025-09-15T10:26:22Z

hi, exposing third party library API (yaml-cpp) as a part of ROS api is not a good idea.

rahul-k-a · 2025-09-15T11:17:02Z

Hi @asherikov , yaml-cpp is used by ROS2 on all platforms, as per my knowledge, since it's a dependency of rclcpp itself (yaml_cpp_vendor is just a wrapper). In that sense I do not consider it foreign to the ROS ecoyststem

asherikov · 2025-09-15T11:59:39Z

API dependency has more implications, e.g., a change in yaml-cpp API would imply a change in ROS2 public API affecting all user code.

Barry-Xu-2018 · 2025-11-13T07:19:35Z

rclcpp/include/rclcpp/parameter_value.hpp

+    if (value_.type != rcl_interfaces::msg::ParameterType::PARAMETER_YAML) {
+      throw ParameterTypeException(ParameterType::PARAMETER_YAML, get_type());
+    }
+    return YAML::Load(value_.yaml_value);


This step may throw an exception during YAML parsing, so it’s best to handle the exception here and output an error log.

Barry-Xu-2018 · 2025-11-13T07:37:40Z

rclcpp/src/rclcpp/node_interfaces/node_parameters.cpp

+std::vector<std::string> __split_parameter_name(const std::string & name)
+{
+  constexpr char delimiter = '.';
+  std::vector<std::string> ret;
+  std::string out;
+  size_t position_found = -1;
+  std::string evaluation_string = name;
+  int counter = 0;
+  // Set an upper limit for the loop
+  // Anyone having more than 100 layers of namespacing should really evaluate their code - Rahul-K-A
+  while(counter++ < 100)
+  {
+    position_found = evaluation_string.find(delimiter);
+    if (std::string::npos == position_found)
+    {
+      break;
+    }
+    ret.push_back( evaluation_string.substr(0, position_found ));
+    evaluation_string = evaluation_string.substr(position_found + 1);
+  }
+  ret.push_back(evaluation_string);
+  return ret;
+}


I don't think it's necessary to limit the number of layers.
In addition, you can use string_view to optimize the code.

namespace { std::vector<std::string> split_parameter_name(const std::string& name) { std::vector<std::string> result; std::string_view str_v(name); size_t pos = 0; while ((pos = str_v.find('.')) != std::string_view::npos) { result.emplace_back(str_v.substr(0, pos)); str_v.remove_prefix(pos + 1); } result.emplace_back(str_v); return result; } }

tfoote · 2026-03-25T01:51:51Z

Cross posting here from #Lyrical Luth Release Working Group > Structured Parameters @ 💬

For visibility:

There's definitely some challenges with the potential duality of this. The parameter types are very limited so we can represent any parameters as a structure, but going the other way we can't set any structure into a parameter. I don't think that we want to enable this sort of dual access. It especially creates a lot of complexity with respect to atomic updates and being able to accept or reject parameter value changes.

At it's core parameters are key value pairs. We use a structure for the keys for convenience, but it's not structurally meaningful in the current implementation.

Looking at the PR it's adding a new paraemter type which is YAML. This is another approach, it would be that there's a large blob in there which is a YAML blob. And we won't be able to provide general introspection into what's encoded in the YAML. We can probably provide a generic yaml markdown/rendering in a text box in most cases. But we can't have a tool plotting a value over time or provide a slider with bounds on it because it's arbitrary data of any type.

An example of this that we've done in the past is embedding URDFs in the robot_description parameter. It's "convenient" but it's also opaque and doesn't really provide much benefit of being a parameter. It also doesn't get logged, and we do now have potential callbacks on parameter changes. You only get a global update callback not one per sub field. And for most dynamic cases we're generally moving to sending the robot description over a topic now.

I think that there's some level that we can support better "native" structured supports for convenience of setting and gettting parameters from the CLI as called out. But I'm not sure that we want to enable adding arbitrary structures into parameters. We have a good way to transport structure data in messages on topics that gives us introspection etc. And we also can't do any prevalidation of arbitrary yaml code. It can only be checked as the right type at runtime by whatever is parsing it.

The other proposal in the past has been to allow parameters to have Message Datatypes. Which is nice that we've already got a lot of capabilities for parsing, rendering and checking. But it also gets into why not just send it as a message on a topic?

rahul-k-a and others added 7 commits August 3, 2025 09:56

chore: Add YAML vendor dependencies to CMake and package.xml

892a2f0

Signed-off-by: Rahul K.A <karahul209@gmail.com>

feat: Add general support for YAML parameter types

6bec0a6

Signed-off-by: Rahul K.A <karahul209@gmail.com>

chore: Fix typo

60b0637

Signed-off-by: Rahul K.A <karahul209@gmail.com>

chore: Apply uncrustify

dd0e66a

Signed-off-by: Rahul K.A <karahul209@gmail.com>

chore: Add additional method of creating YAML parameter value

f36c794

Signed-off-by: Rahul K.A <karahul209@gmail.com>

chore: Add additional method of creating YAML parameter value

c25ae28

Signed-off-by: Rahul K.A <karahul209@gmail.com>

Merge branch 'ros2:rolling' into add-structured-parameter-support

a52fc85

rahul-k-a mentioned this pull request Aug 30, 2025

[Draft]Add structured parameter support ros2/rcl#1254

Open

This was referenced Aug 30, 2025

Add structured parameter support ros2/rcl_interfaces#183

Open

[Draft]Add structured parameter support ros2/rclpy#1494

Open

rahul-k-a changed the title ~~Add structured parameter support~~ [Draft]Add structured parameter support Aug 30, 2025

rahul-k-a mentioned this pull request Aug 30, 2025

YAML parser: support mixed types ros2/rcl#463

Open

ahcorde requested changes Sep 8, 2025

View reviewed changes

Barry-Xu-2018 reviewed Nov 13, 2025

View reviewed changes

christophebedard mentioned this pull request Jan 6, 2026

Support structured parameters ros2/ros2#1734

Open

		explicit ParameterValue(const std::vector<std::string> & string_array_value);


		/// Generate a parameter value with type PARAMETER_YAML

Conversation

rahul-k-a commented Aug 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Is this user-facing behavior change?

Did you use Generative AI?

Additional Information

Uh oh!

rahul-k-a commented Aug 30, 2025

Uh oh!

rahul-k-a commented Aug 30, 2025

Uh oh!

alsora commented Sep 6, 2025

Uh oh!

ahcorde left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

asherikov commented Sep 15, 2025

Uh oh!

rahul-k-a commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

asherikov commented Sep 15, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tfoote commented Mar 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

rahul-k-a commented Aug 30, 2025 •

edited

Loading

rahul-k-a commented Sep 15, 2025 •

edited

Loading