Invitation to Collaborate on AsyncAPI Specification for ROS2

[flo]

Dear ROS Community Members,

We are excited to announce that we are crafting a standard message representation for ROS2 using AsyncAPI. A draft is already available on GitHub, and we warmly invite the ROS community to join us in refining this specification. Your input is invaluable, and we encourage you to participate in the ongoing discussions.

Right now, we have developed an AsyncAPI binding for ROS2, and there’s a vibrant conversation happening on GitHub. To enhance collaboration, we’re planning to hold an open discussion session. To help us find a time that suits everyone, please indicate your availability using the Microsoft Forms link below:

Indicate Your Availability Here

Slot 1: 2025-04-08T12:00:00Z→2025-04-08T13:00:00Z

Slot 2: 2025-04-09T12:00:00Z→2025-04-09T13:00:00Z

Slot 3: 2025-04-10T08:00:00Z→2025-04-10T09:00:00Z

Slot 4: 2025-04-10T14:00:00Z→2025-04-10T15:00:00Z

If you’re interested in learning more about AsyncAPI and its significance for ROS2 users, we invite you to watch the ROSCon DE talk we presented last year:

Watch the ROSCon DE Talk - PDF
( @destogl would you please help us access the video recording, please?)

Join the discussion on GitHub:

AsyncAPI Specification Draft on GitHub

We look forward to your contributions and to meeting you all soon!

Best regards,

Florian

This Communication is part of the aerOS project that has received funding from the European Union’s Horizon Europe research and innovation programme under grant agreement Nº101069732

[gavanderhoorn]

I’ve looked at the PR and posted some (very minor) comments.

Something that kept bothering me while reading up on AsyncAPI and reading the PR is the fact I’m not sure there isn’t a mismatch between (some of) the concepts in AsyncAPI and a typical ROS API (which I believe you’re trying to model using either one or multiple AsyncAPI documents).

The AsyncAPI specifically describes it as being used for modelling event driven architectures, which is certainly something ROS can be used for, but I’m wondering at which level services and actions would need to be described to really match with AsyncAPIs concepts (I believe the need to introduce custom properties for instance (role?) is a consequence of this).

Note: I’m not an AsyncAPI expert, far from it, so this may be all due to misunderstanding their documentation.

[ebowei]

This is awesome! I’m pretty new to the community, and I want to be involved. Can I make useful contributions to this as a beginner? Would love some guidance.

[Achllle]

I want to point out that there is an existing way to define a ROS 2 API - NoDL. I believe AsyncAPI may be worth the shot, even though NoDL is made specifically for ROS 2 given AsyncAPI has a sizable community and includes tools for visualizing the API as well as standards and examples for generating code from an API spec. While this may feel like the xkcd standards situation, AsyncAPI has received a lot more support from other open-source communities, while NoDL seems to have been abandoned shortly after conception. Just my 2c, would love to hear other opinions.

[flo]

Hello again,

Thank you for your valuable input so far! I am looking forward to discuss them with you tomorrow.

The poll has drawn towards the first meeting slot.
So therefore, I’ll post here the link for our meeting tomorrow and warmly invite all interested parties to join the open meeting.

Currently, this is our agenda:

Time is: Slot 1: 2025-04-08T12:00:00Z→2025-04-08T13:00:00Z

Join conversation

In the meantime, there is now also the recording available to my ROSConDE`24 talk about AsyncAPI:

Empowering ROS Users in Industry and Research with Industrial Automation...

Looking forward to tomorrow!
Cheers

[Achllle]

Unfortunately that time slot excludes West Coast USA (except maybe a few morning birds at 5am). If we can’t do an additional time slot, can the session be recorded and shared?

[flo]

We are having our discussion here now:

Join conversation

We try to record it and find another session for the west cost

[RFRIEDM]

Thanks! I’ll catch up this afternoon. Thanks for spearheading this!

[steve-jobs]

When is the next meeting?

---- Replied Message ----

From | Florian Gramß via ROS Discoursenotifications@ros.discoursemail.com |

• | - |
  Date | 04/08/2025 20:27 |
  To | 15651859189@163.com |
  Cc | |
  Subject | [ROS Discourse] [General] Invitation to Collaborate on AsyncAPI Specification for ROS2 |

| flo
April 8 |

• | - |

We are having our discussion here now:

Microsoft Teams
### Join conversation

We try to record it and find another session for the west cost

[amparo-siemens]

Meeting Minutes

Please feel free to reach out for the meeting recording at research.industry@siemens.com if needed. We would appreciate your feedback on interest in follow-up meetings—please thumbs up to this message if interested in having a call on 2025-04-17T15:00:00Z→2025-04-17T16:00:00Z!

Attendees:

• Florian Gramß (Siemens): @flo
• Amparo Sancho Arellano (Siemens): @amparo-siemens
• Ramon Wijnands (Nobleo)
• Tim Clephas (Nobleo): @Timple
• @steve-jobs

Introduction: Florian introduced the purpose of the meeting, explaining Siemens’ efforts on an AsyncAPI specification for ROS 2, originally presented at ROSCon Germany. Progress has led to the contribution phase with an open pull request: GitHub PR #270. The aim is to receive community feedback rather than unilaterally defining the specification.

Key Discussion Points

Message Type References

• Discussed how to reference message types in the AsyncAPI specification
• Two approaches were considered:
  1. File-based references (copying the message definition)
  2. URL-based references (pointing to message definitions stored elsewhere)

Repository Structure Considerations

• Ramon mentioned their team is moving from multi-repository to mono-repository development to keep things in sync
• Different approaches might be needed based on repository structure:
  • For mono-repositories: file-based references might be sufficient
  • For distributed/multi-repositories: URL-based references might be more appropriate
• Even with multiple repositories, once checked out locally, relative references could work

Documentation Concerns

• There was a concern about duplicating the same information in different formats
• A suggestion was made to dynamically pull information from URLs (either online or local) when viewing documentation

Ideas and Suggestions

1. CI Integration
   • Implement CI checks to verify documentation and AsyncAPI specs remain in sync
2. Build System Integration
   • Add code generation as part of the colcon build process to obtain directly the AsyncAPI specification
3. Validation
   • Develop a validator to ensure implementations comply with standards
   • Could be integrated into CI pipelines
4. Documentation Distribution
   • Some AsyncAPI HTML format documentation should be part of a code repository (like github)
5. Repository Structure Considerations
   • Consider implications of mono-repository vs. multiple-repository setups
   • URL references to message definitions (online or offline) might be beneficial

Next Steps:

1. Proceed with the Initial Pull Request:
   • Finalize the PR for ROS 2 integration into AsyncAPI as introduced by ROS2 bindings #254.
2. Decision on URL-based Referencing:
   • Determine the feasibility and agreement on using URL-based references for message types.
3. Documentation Management:
   • Ensure that AsyncAPI files are represented and appropriately managed on GitHub as both file and HTML formats.
4. Engage with Community:
   • Continuously gather feedback to determine interest in follow-up meetings.
   • Evaluate and implement community suggestions for maintaining ROS 2 AsyncAPI specifications.

Special thanks to @Timple and Ramon Wijnands for the interesting call we had!

[amparo-siemens]

Since it seems that there is no more open points to have another discussion, we will proceed with the finalization of the pull request!

[RFRIEDM]

Sorry, missed the last meeting!

Have you considered instead of relying on a URL or relative path to the Async API doc, that you could instead use the path relative to the package prefix? ROS messages in a workspace are unique. For example, there is only one geometry_msgs/msg/Point.

This gives you ability to not worry about where your messages come from, and where they are relative to the AsyncAPI spec.

Is it a fair assumption that those writing async API specs:

1. source their ROS workspace
2. “ros2 pkg prefix --share geometry_msgs” should work

If both of those are true, then the problem might be a lot easier to solve in a way already used by lots of ROS tooling.

[amparo-siemens]

Thank you for your suggestion on using the path relative to the package prefix for referencing ROS message types in the AsyncAPI specification. It’s an interesting approach and indeed aligns with current ROS tooling practices.

However, there are some points we need to consider:

1. Translation to AsyncAPI Format: While using the package prefix can simplify locating the message definitions within a workspace, it is important to remember that these definitions need to be translated into the AsyncAPI format. This transformation is necessary for the specification to effectively describe the interface as intended.

2. Workspace Access: Your approach assumes that developers have access to the ROS workspace where these messages are defined. While this might be true in many cases, we need to ensure this solution is flexible enough to accommodate scenarios where direct access to a workspace is not available—such as a machine already running without the source code.

3. AsyncAPI Independence: AsyncAPI holds information independently of its source environment. This characteristic allows it to be accessed and understood regardless of where the reference points originate. Therefore, maintaining synchronization between ROS message definitions and AsyncAPI specifications through either manual processes or automated CI/CD workflows is crucial.

4. Unique Message Assurance: While the package prefix should theoretically guarantee uniqueness of message types within a workspace, there are broader implications for ensuring these messages remain synchronized and correctly reflected in the AsyncAPI documentation—considering updates, changes, or variations among different development setups.

What we could consider is adding another field called origin-definition or something similar. This field could include a pointer to a URL or a local file link, providing a direct reference to the original message definition for easier tracking and validation. @Achllle, we would love to hear your thoughts on this approach.

Additionally, it’s important to note that we cannot change the way AsyncAPI relies on having a copy of the message definition in the AsyncAPI format. While we recognize that this might not be ideal, altering the existing tools and practices widely adopted in the AsyncAPI ecosystem is not feasible.

We appreciate the collaboration and exchange of ideas to establish robust solutions for ROS 2 AsyncAPI specifications. If you have any additional thoughts, or would like further discussion, feel free to reach out. Looking forward to evolving this project together!

[Achllle]

If we’re going to include the full message definition in the spec, then adding another field to point to a different source is just going to lead to partial implementations where folks don’t always link to this extra field. If it’s required, it just means adding effort.

The only and big exception I would make to this are the common_interfaces packaged in each ROS 2 distro. I don’t think anyone will use this if it means they have to spell out every single interface from this manually. Alternatively someone maintains an asyncAPI version of all these interfaces that matches a release and people can refer to them that way.

[RFRIEDM]

@amparo-siemens

is important to remember that these definitions need to be translated into the AsyncAPI format.

Sorry for the delay. Your reasoning makes sense.

Just a note on #2 - the standard ROS packaging exports message definitions in the share directory of the package; they are available in all binaries for tier 1 platforms. It does not require the repo cloned in a source workspace.

For example, on Ubuntu Noble with a binary ROS jazzy install:

$ find $(ros2 pkg prefix --share std_msgs) -name *.msg
/opt/ros/jazzy/share/std_msgs/msg/UInt16MultiArray.msg
/opt/ros/jazzy/share/std_msgs/msg/UInt8.msg
/opt/ros/jazzy/share/std_msgs/msg/UInt64.msg
/opt/ros/jazzy/share/std_msgs/msg/Bool.msg
/opt/ros/jazzy/share/std_msgs/msg/MultiArrayDimension.msg
/opt/ros/jazzy/share/std_msgs/msg/UInt32MultiArray.msg
/opt/ros/jazzy/share/std_msgs/msg/String.msg
/opt/ros/jazzy/share/std_msgs/msg/Float64.msg
/opt/ros/jazzy/share/std_msgs/msg/MultiArrayLayout.msg
/opt/ros/jazzy/share/std_msgs/msg/Header.msg
/opt/ros/jazzy/share/std_msgs/msg/UInt8MultiArray.msg
/opt/ros/jazzy/share/std_msgs/msg/Byte.msg
/opt/ros/jazzy/share/std_msgs/msg/Int32.msg
/opt/ros/jazzy/share/std_msgs/msg/Int16MultiArray.msg
/opt/ros/jazzy/share/std_msgs/msg/Float64MultiArray.msg
/opt/ros/jazzy/share/std_msgs/msg/Float32MultiArray.msg
/opt/ros/jazzy/share/std_msgs/msg/UInt64MultiArray.msg
/opt/ros/jazzy/share/std_msgs/msg/Empty.msg
/opt/ros/jazzy/share/std_msgs/msg/ByteMultiArray.msg
/opt/ros/jazzy/share/std_msgs/msg/Int16.msg
/opt/ros/jazzy/share/std_msgs/msg/UInt16.msg
/opt/ros/jazzy/share/std_msgs/msg/Int8MultiArray.msg
/opt/ros/jazzy/share/std_msgs/msg/Int64MultiArray.msg
/opt/ros/jazzy/share/std_msgs/msg/Int8.msg
/opt/ros/jazzy/share/std_msgs/msg/Int32MultiArray.msg
/opt/ros/jazzy/share/std_msgs/msg/Float32.msg
/opt/ros/jazzy/share/std_msgs/msg/Int64.msg
/opt/ros/jazzy/share/std_msgs/msg/Char.msg
/opt/ros/jazzy/share/std_msgs/msg/UInt32.msg
/opt/ros/jazzy/share/std_msgs/msg/ColorRGBA.msg

I think it would be at least nice if there was tooling to covert from the the .msg, .srv, and action or .idl format given a package name. The install directory has standard conventions.