REP §2.0: clarify declarative Ros*API authoring vs simulator execution artifacts by rgasoto · Pull Request #29 · RobotecAI/wip-openusd-interoperability-rep

rgasoto · 2026-04-21T18:56:07Z

Summary

Adds a new §2.0 establishing the boundary between authored Ros*API schemas (declarative, portable, single source of truth) and simulator-native execution artifacts (OmniGraph in Isaac Sim, Gazebo system plugins, O3DE components).

Gives simulators with existing imperative execution layers a clear conformance path: generate the execution artifact from Ros*API at load time, keep it in the proprietary layer, never shadow the authored data.

Non-normative with respect to the code-generator API itself; leaves each simulator free to implement its own generator, share one, or parse the schemas at runtime. Compliance is measured against the authored data, not the generated artifact.

Commit layout

Clarify declarative authoring vs simulator execution artifacts — content (single squashed commit).
refactor(layer-encoding) — .usd → .usda in branch-owned text. Drop if upstream rejects #rep-layer-encoding.

Dependencies

None.

Provenance

Priority Action #5 in the comparative review.

Made with Cursor

Add a new Section 2.0 establishing the boundary between authored Ros*API schemas (declarative, portable, single source of truth) and simulator-native execution artifacts (OmniGraph in Isaac Sim, Gazebo system plugins, O3DE components). Gives simulators with existing imperative execution layers a clear conformance path: generate the execution artifact from Ros*API at load time, keep it in the proprietary layer, never shadow the authored data. Non-normative with respect to the code-generator API itself; leaves each simulator free to implement its own generator, share one, or parse the schemas at runtime. Compliance is measured against the authored data, not the generated artifact. Add Renato Gasoto (NVIDIA) to authors. Made-with: Cursor

…e for topic name as well

rgasoto · 2026-04-24T14:36:09Z


 *   **Explicit TF Broadcasting (`RosFrameAPI`):** To publish TFs for non-physical dummy frames (e.g., a kinematic `grasp_point`, a `camera_optical_frame`), asset authors must apply the `RosFrameAPI` schema to the target `UsdGeomXform` Prim.
-    *   `string ros:frame:id` (Optional): Overrides the TF frame name. If omitted, the validated Prim name is used.
+    *   `string ros:frame:id` (Optional): Overrides the TF frame name. If omitted, the validated Prim Display name is used, falling back to the Prim name if Display name is not authored.


Adding a note on this suggestion - I'm not entirely convinced we need the frame_id, Display name should cover the change from what the Prim name is, and give a more relaxed validation criteria than Prim name.

Needs Follow up on the consolidation of redundant schemas - FrameAPI is very similar to Robot's Schema SiteAPI, its goal is providing this common neutral place to define a robot structure. Granted that The robot schema is still not Fully neutral since it's being developed under Nvidia's governance, but if its architecture is approved and we put it on a open body governance it should contain the informations we need here, and we can incorporate more as needs surface.

rgasoto · 2026-04-24T14:39:13Z


 A number of concepts in ROS (e.g. robot descriptions, controllers) rely on joints names. 
-To ensure that joints are correctly identified and mapped to said concepts, the custom property `ros:joint:name` must be applied to all Prims bearing built-in `UsdPhysicsJoint` schema. 
+To ensure that joints are correctly identified and mapped to said concepts, the custom property `ros:joint:name` must be applied to all Prims bearing built-in `UsdPhysicsJoint` schema.


Same note as above, not sure that we need a ros:joint:name if we can directly use Core USD DisplayName, which allows for a much broader stringset that covers ros naming, and would be more easily adopted over different engines.

zakmat

@rgasoto thank you for your contribution.

I'd suggest closing this PR in the current form. Please see the comments for the details

I am currently extracting the normative rules from this and other PR-s and will tag you as co-author.

zakmat · 2026-04-27T11:33:18Z


 *   **Explicit TF Broadcasting (`RosFrameAPI`):** To publish TFs for non-physical dummy frames (e.g., a kinematic `grasp_point`, a `camera_optical_frame`), asset authors must apply the `RosFrameAPI` schema to the target `UsdGeomXform` Prim.
-    *   `string ros:frame:id` (Optional): Overrides the TF frame name. If omitted, the validated Prim name is used.
+    *   `string ros:frame:id` (Optional): Overrides the TF frame name. If omitted, the validated Prim Display name is used, falling back to the Prim name if Display name is not authored.


1.2.5 already aligns this REP with PixarAnimationStudios/OpenUSD-proposals#105 which specifically argues against using displayName as an external identifier. Adding displayName as fallback is exactly the conflation the 105 calls out.
ROS names have grammar constraints that displayName does not enforce. Current prim name fallback on the other hand carry those constraints.

zakmat · 2026-04-27T11:35:59Z


 A number of concepts in ROS (e.g. robot descriptions, controllers) rely on joints names. 
-To ensure that joints are correctly identified and mapped to said concepts, the custom property `ros:joint:name` must be applied to all Prims bearing built-in `UsdPhysicsJoint` schema. 
+To ensure that joints are correctly identified and mapped to said concepts, the custom property `ros:joint:name` must be applied to all Prims bearing built-in `UsdPhysicsJoint` schema.


see the comment on ros:frame:id. The same applies here, we should not conflate UI human readable identifiers with the interface contracts

zakmat · 2026-04-27T13:37:33Z

+### 2.0 Declarative Intent and Source of Truth
+
+The `Ros*API` schemas are **declarative authored data** describing *what* ROS interfaces an asset exposes. They do not prescribe *how* a simulator realizes those interfaces at runtime. The mechanism a simulator uses to bind a declared interface to its internal message I/O is an implementation detail outside the scope of this REP.
+
+Three authoring rules follow from this separation:
+
+1.  **The authored `Ros*API` schemas are the single source of truth for ROS interface intent.** Any simulator-native runtime artifact derived from them must remain consistent with the authored data. Assets must not carry duplicated or shadow definitions of the same ROS interface in another form (e.g., a hand-authored execution graph or a proprietary attribute set) that could diverge from the `Ros*API` schemas.
+2.  **Simulator-native runtime artifacts are proprietary-layer content.** When a simulator chooses to materialize the authored intent into a persisted, simulator-specific representation, that representation must be confined to the simulator's proprietary layer (Section 1.2.1) and must never be authored into the neutral `ros.usda` layer.
+3. Round-tripping of simulator-native runtime artifacts across simulators is not guaranteed; only the authored `Ros*API` schemas are portable.


The normative content here is mostly already covered by two existing passages:

2 preamble:

This section defines a set of declarative, engine-agnostic API schemas (of type SingleApply). Simulators are responsible for reading these schemas and generating their respective underlying execution logic.

1.2.1 Proprietary Layer

Simulator-specific implementations (e.g., proprietary execution graphs) must be limited to what is strictly necessary and confined to a separate proprietary layer.

Together these establish:

schemas are the authored intent,

simulators generate execution logic from them, and

any persisted runtime artifacts live in the proprietary layer

Note the explicit mention of proprietary execution graphs.

Point 1. is providing good additive rules, worth to keep those. I would suggest combining with the existing preamble of this section

Understood, I'll review the PR to address your comments

adamdbrw · 2026-04-29T14:26:10Z

Selectively applied in #34 and #33. Thank you!

rgasoto added 3 commits April 21, 2026 14:37

refactor(layer-encoding): write .usda in branch-owned path mentions

3ee029c

Update Ros*API wording to be less vendor-specific; Use of display nam…

55415c1

…e for topic name as well

rgasoto commented Apr 24, 2026

View reviewed changes

zakmat reviewed Apr 27, 2026

View reviewed changes

adamdbrw closed this Apr 29, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

REP §2.0: clarify declarative Ros*API authoring vs simulator execution artifacts - #29

REP §2.0: clarify declarative Ros*API authoring vs simulator execution artifacts#29
rgasoto wants to merge 3 commits into
RobotecAI:mainfrom
rgasoto:rep-codegen-guidance

rgasoto commented Apr 21, 2026

Uh oh!

rgasoto Apr 24, 2026

Uh oh!

rgasoto Apr 24, 2026

Uh oh!

zakmat left a comment

Uh oh!

zakmat Apr 27, 2026

Uh oh!

zakmat Apr 27, 2026

Uh oh!

zakmat Apr 27, 2026

Uh oh!

rgasoto Apr 27, 2026

Uh oh!

adamdbrw commented Apr 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

rgasoto commented Apr 21, 2026

Summary

Commit layout

Dependencies

Provenance

Uh oh!

rgasoto Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

rgasoto Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

zakmat left a comment

Choose a reason for hiding this comment

Uh oh!

zakmat Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

zakmat Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

zakmat Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

rgasoto Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

adamdbrw commented Apr 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants