Semantic Robot Description Format (SRDF) review

Proposer: Sachin Chitta, Kaijen Hsiao, Gil Jones, Ioan Sucan, John Hsu


This format is intended to represent information about the robot that is not in the URDF file, but it is useful for a variety of applications. The intention is to include information that has a semantic aspect to it.

One thing to note is that there is also a proposal to add a sensor definition to the URDF format, as well as officially supporting the <mimic> tag for a joint. Those extensions would actually be handled by the URDF parser, and would not be part of this format.



  • <robot> element

    • Purpose: This is the root tag that for this document. All information is included in this tag.
    • Elements: <group>, <end_effector>, <virtual_joint>, <group_state>, <disable_collisions>

    • Attributes:
      • name is the name of the robot. It should be the same name as in the corresponding URDF file.

  • <group> element

    • Purpose: Representation of a set of joints and links. This can be useful for specifying DOF to plan for, defining arms, end effectors, etc
    • Elements: <link>, <joint>, <chain>, <group>

    • Attributes:
      • name is the name of the group

    • Note: when a group contains no tags, only its name attribute, it is assumed to be a reference to a group with that name, but that is defined earlier.
  • <group_state> element

    • Purpose: Define a named state for a particular group, in terms of joint values. This is useful to define states like "folded arms".
    • Elements: <joint>

    • Attributes:
      • name is the name of the state

      • group is the name of the group the state is for

    • Note: all joints in a group must have their value specified as part of a group state in order for that state to be valid.
  • <link> element

    • Purpose: this element specifies a link that is part of a <group>.

    • Elements: none
    • Attributes:
      • name must be a name of a link in the corresponding URDF file

    • Note: When a link is included in a group, so is the corresponding parent joint (if one exists)
  • <joint> element

    • Purpose: this element specifies a joint that is part of a <group>.

    • Elements: none
    • Attributes:
      • name must be a name of a joint in the corresponding URDF file

      • value *only* in the <group_state> tag, the value attribute is accepted for joints (a floating point value). When a joint consists of multiple DOF, the value is simply a space-separated array of floating point values.

    • Note: When a joint is included in a group, so is the corresponding child link
  • <chain> element

    • Purpose: Represent a kinematic chain in the robot. This is useful for instance in representing arms.
    • Elements: none
    • Attributes:
      • base_link is the root link of the chain (the link that is fixed with respect to the chain)

      • tip_link is the last link of the chain (where the chain ends)

    • Note: Based on the links in the chain, the set of joints in the chain is implicitly defined. The joints that correspond to a chain are the parent joints for the links in the chain, except the parent joint of the base_link.

  • <end_effector> element

    • Purpose: Represent information about an end effector.
    • Elements: none
    • Attributes:
      • name is the name of the end effector

      • parent_link is the name of the link this end effector is attached to.

      • group is the name of the group that contains the links (and joints) that make up the end effector

  • <virtual_joint> element

    • Purpose: this element defines a virtual joint between a robot link and an external frame of reference (considered fixed with respect to the robot)
    • Elements: none
    • Attributes:
      • name the name of the joint that is assumed to exist between the robot and the environment

      • child_link the name of the link that connects the robot to the environment

      • parent_frame the name of the frame assumed to be fixed with respect to the robot

      • type the type of joint to be assumed. This can be fixed (0 DOF), floating (all 6 DOF) or planar (3 DOF: x, y, yaw)

    • Note: When the <joint> tag is used to refer to existing joints by name, using the name of defined virtual joints is also possible.

  • <disable_collisions> element

    • Purpose: By default it is assumed that any link of the robot could potentially come into collision with any other link in the robot. This tag disables collision checking between a specified pair of links. There can be many such tags in this file
    • Elements: none
    • Attributes:
      • link1 the name of the first link in the pair

      • link2 the name of the second link in the pair

Generic Example

<?xml version="1.0"?>

 <!-- This does not replace URDF, and is not an extension of URDF.
      This is a format for representing semantic information about the robot structure.
      A URDF file must exist for this robot as well, where the joints and the links that are referenced are defined -->
 <robot name="some robot">

   <group name="group1">
      <!-- when a link is specified, the parent joint of that link (if it exists) is automatically included -->
      <link name="..."/>
      <link name="..."/>

      <!-- when a joint is specified, the child link of that joint (which will always exist) is automatically included -->
      <joint name="..." />

      <!-- when a chain is specified, all the links along the chain (including endpoints) are included in the group. Additionally, all the joints that are parents to included links are also included. This means that joints along the chain and the parent joint of the base link are included in the group -->
      <chain base_link="l_shoulder_pan_link" tip_link="l_wrist_roll_link"/>
      <chain base_link="r_shoulder_pan_link" tip_link="r_wrist_roll_link"/>

   <!-- groups can also be formed by referencing to already defined group names -->
   <group name="arms">
      <group name="left_arm"/>
      <group name="right_arm"/>
      <link name="..." />

   <!-- define a named state/configuration of a group -->
   <group_state name="name of this state" group="name of group the state is for">
      <joint name="name of joint in group" value="" />
      <!-- all joints must be specified for the state to be valid -->

   <!-- Define how the robot moves in its environment, i.e., connection to robot's root link -->
   <virtual_joint name="world_joint" type="planar" parent_frame="some fixed frame" child_link="robot's root link name"/> <!-- type can be planar, floating or fixed -->

   <!-- We can then include the virtual joint in groups -->
   <group name="whole_body">
      <group name="arms"/>
      <joint name="world_joint"/>

   <!-- define end effectors -->
   <end_effector name="some diff name" parent_link="..." group="group_name"/>

   <!-- By default it is assumed that any link of the robot could potentially come into collision with any other link in the robot. This tag disables collision checking between a specified pair of links. There can be many such tags in this file.-->
   <disable_collisions link1="link1" link2="link2" />


Example for the PR2

<?xml version="1.0"?>

<robot name="pr2">

   <virtual_joint name="world_joint" type="planar" parent_frame="odom" child_link="base_footprint"/> 

   <group name="right_arm">
      <chain base_link="torso_lift_link" tip_link="r_wrist_roll_link"/>

   <group name="left_arm">
      <chain base_link="torso_lift_link" tip_link="l_wrist_roll_link"/>

   <group name="arms">
      <group name="left_arm"/>
      <group name="right_arm"/>

   <group_state name="tuck_arms" group="arms">
      <joint name="l_shoulder_pan_joint" value="0.2" />
      <!-- ... the rest of the joint values... -->

   <group name="base">
      <joint name="world_joint"/>

   <group name="whole_body">
      <group name="arms"/>
      <group name="base"/>
      <joint name="torso_lift_joint"/>

   <group name="l_end_effector">
      <joint name="l_gripper_palm_joint" />
      <joint name="l_gripper_l_finger_joint" />
      <joint name="l_gripper_l_finger_tip_joint" />
      <joint name="l_gripper_led_joint" />
      <joint name="l_gripper_motor_accelerometer_joint" />
      <joint name="l_gripper_motor_slider_joint" />
      <joint name="l_gripper_motor_screw_joint" />
      <joint name="l_gripper_r_finger_joint" />
      <joint name="l_gripper_r_finger_tip_joint" />
      <joint name="l_gripper_joint" />
      <joint name="l_gripper_tool_joint" />

   <group name="r_end_effector">
      <joint name="r_gripper_palm_joint" />
      <joint name="r_gripper_l_finger_joint" />
      <joint name="r_gripper_l_finger_tip_joint" />
      <joint name="r_gripper_led_joint" />
      <joint name="r_gripper_motor_accelerometer_joint" />
      <joint name="r_gripper_motor_slider_joint" />
      <joint name="r_gripper_motor_screw_joint" />
      <joint name="r_gripper_r_finger_joint" />
      <joint name="r_gripper_r_finger_tip_joint" />
      <joint name="r_gripper_joint" />
      <joint name="r_gripper_tool_joint" />

   <end_effector name="r_end_effector" parent_link="r_wrist_roll_link" group="r_end_effector"/>
   <end_effector name="l_end_effector" parent_link="l_wrist_roll_link" group="l_end_effector"/>

   <disable_collisions link1="r_shoulder_pan_link" link2="r_shoulder_lift_link" />
   <!-- and many more disable_collisions tags -->


Question / concerns / comments

Enter your thoughts on the API and any questions / concerns you have here. Please sign your name. Anything you want to address in the API review should be marked down here before the start of the meeting.

Jonathan Bohren

  • Why should this be an entirely new format instead of an extension to the URDF? It seems like there's a lot of common information between the two formats.
  • If the idea is that not all users of a robot's URDF might not need the semantic information, maybe it would be cleaner to add an interface to augment a loaded URDF on-line, instead of having an entirely different specification that duplicates information?

Shaun Edwards

  • I second Jonathan's firt point. There is some overlap between urdf and the proposed srdf. Why not add these items to the urdf format as extensions
  • Some the the proposed items (collisions for example) must already be captured somewhere. I know the arm navigation wizard performs some analysis to determine which links are never in collision. Where is this stored currently? Why change it?
  • I'd like to expand on the "end_effector" item. Something that is missing from urdf and srdf is the idea of a tool point (or atleast it's not clear to me how to specify them). Industrial robots use a tool point in order to define multiple locations on an end effector or grasped object about which motion should be defined. A good example may be a multi-tool end-effector, one that includes a screw driver, wrench, etc...) Each tool should have it's own tool-point so that motion could be specified relative to that point (i.e. a pure rotation about a screw axis).

Mike Ferguson

  • I'd also like to see this unified with the URDF if possible.
  • I'd also like to see some sort of "tool point" like definition. I know on my own robot I currently define two different TF frames (one for pinching grasps and a second for enveloping grasps).
  • This seems to cover mostly actuator semantics, can we also look at adding sensor semantics? The URDF spec already has a <sensor> tag for PR2 on gazebo, by adding a more general <sensor> tag, we can allow serious introspection into what the capabilities of a robot are. I'd propose something like:

    • <sensor> element

      • Purpose: Represent a sensor on the robot. This is useful for introspecting sensory capabilities.
      • Elements: none
      • Attributes:
        • name is the name of the sensor

        • type a string representing the type of sensor, for instance, "laser", "camera2d", "rgbd", etc...

        • topic is the name of the topic the sensor publishes to. Perhaps this is actually made into an element for sensors that broadcast multiple topics? If so, maybe "type" is better suited in that element?

        • link is the link where the sensor is connected

E. Gil Jones

Comments to the above:

  • You can think of this as an extension of the URDF, but would not be parsed by the URDF. We don't limit URDF extensions in anyway - they are ignored by the URDF parser. As long as the right parser is invoked that fills out the data structure that corresponds to this file, the actual description can live anywhere.
  • I put a note up at the top, but there's a related to proposal to promote the <sensor> tag to official URDF support - it would be included in the parsed data structure. If you have suggestions of the way that format should look this is a fine place to put them until there's a Fuerte URDF review.

Thibault Kruse

Work has been done in our lab published in ICRA 2011 "Towards Semantic Robot Description Languages", by Lars Kunze and Tobias Roehm and Michael Beetz. While that was not a lightweight XML extention to URDF, inspiration may be drawn from it. PDF link

I am aware anyone can extend URDF for their own purpose, so i will just give ideas that crossed my mind.

  • The end_effector tag could allow more information about the type, just like sensor. E.g. whether it is a wheel, a gripper, or something funny like the moving lips of a social robot, or eyelids used for winking (see movie iRobot).
  • Similarly, for HRI, it would be good if it was possible to derive the required joint data for actions "nodd", "shake head", "look at" and "point at" from the URDF. In particular for humanoid robots this would indicate "head" joints as well as their primary orientation, or the same for "pointer" joints. Because in HRI "look at" might imply more than something being in the FOV of any sensor, but rather the robot indicating attention or engagement by displaying a watching pose. In particular a pointing gesture with any kind of hand involves stretching the index finger and rolling in all other fingers of a hand. A "thumbs up" does the same for a thumb. And a thumbs up looks different from showing a stretched middle finger. Of course xml structure needs to taking to account that a robot might have non-humanoid shapes with n arms, m hands and k heads.
  • I think it might also be useful to allow including default poses, such as parked arm poses, shutdown pose, passive pose (passive indicating the robot is switched on, but not doing anything).
  • I know little about URDF, if not possible already, the mechanical joint limits (velocity limits) as well as data about the physical attributes of actuators could be included as well for reasoning. Such as motor model (by reference id), using which one can look up e.g. motor strength or energy consumption. Also weight of links. I see there is a "transmission" tag, but it seems to not be meant for general usage.
  • (maybe this does not belong here) Unless already possible, it could be useful if URDFs for off-the-shelf components could be used from separate files. Such as the KUKA LWR or the Kinect. This would also imply that namespaces are managed such that 2 similar arms get individual joint names. The same principle holds for modular robots. If a hand, arm or a head can be exchanged, separate files should be used for each component. While this is of course technically possible anyway, it would be good if Willow demonstrated the way it is done for others to follow the lead.

Moritz Tenorth

The work Thibault referred to is also available in ROS: Its objective is also to add semantics to the URDF specification, and SRDL is in some parts similar to this proposal (e.g. that parts of kinematic chains can be annotated to be a hand or an arm). However, there are some differences:

  1. As file format, we use OWL, which is still a valid XML document and can be treated as such, but the semantics of the nodes and attributes are well defined by linking the description to a robot ontology in the KnowRob knowledge base. This allows to load the description into the knowledge base and perform reasoning about e.g. which components a robot has.

  2. Apart from hardware components like sensors and actuators, the system also supports software components and abstract capabilities (e.g. navigation or object recognition). These capabilities can usually be provided in different ways, and we are working on heuristics to determine their presence automatically (e.g. navigation capabilities are present if a move_base action is available).
  3. One can specify requirements an action has in terms of components and capabilities, and match them against a robot description in SRDL. This allows to verify that a robot has the capabilities it needs to perform the task and to determine which ones are missing.

SRDL is used in the RoboEarth project ( for determining which capabilities are required to perform an action. RoboEarth works on exchanging knowledge about actions, objects and the environment between robots, and being able to decide if a task description is suitable for a robot is an important reasoning task in this application.

David Lu!!

I am glad to see this area getting some attention. My instinct is to agree with everyone who says that this should integrated with URDF.

  1. There was talk (in tickets and on ros-users) of "URDF 2.0". Are there any official plans for that? Are these those plans?
  2. One thing I had mentioned long ago on ros-users was that some of these things (especially grouping) are already contained in the files via xacro macros. We already write URDF in a way that they are grouped; I feel we should be able to extend that format to include this information.

  3. While we're upheaving things, I'd really love to see gazebo tags disappear in favor of more generic meaningful labels.
  4. Similarly, I'm glad to see that mimic and sensor are being officiated. Any reason transmission is being left out?

Adolfo Rodriguez Tsouroukdissian

  • The data that is being proposed for the SRDF currently exists in the arm_navigation package, in the form of yaml files that set ROS params. Probably one of the things that should be highlighted is the rationale behind the move from one persistent storage form to another. Is it to have a more arm_navigation- or ros-agnostic representation?.
  • As a follow-up of the above point, I'd be also interested in knowing what other description formats have been evaluated (and possibly discarded). I favor extending specifications that satisfy existing requirements and have a large user base, even if our extension is domain-specific and will not be used by the larger community. In particular, I'd like to know your opinion on extending the Collada spec, by means of the <extra> tag paired with a domain-specific schema (as opposed to creating a whole new description format). For the robot model, moving away from URDF towards Collada is very convenient as it allows us to speak a common tongue with mechanical engineers and graphic designers. I'd like to keep additional (related) data such as what is proposed here also represented in that same common tongue (not necessarily the same file), even if a graphic designer will find no use for it.

Review is now closed


  • The Willow Garage team would like to thank all the reviewers for their help! The following changes were made after the review:
  • Added the <group_state> tag to represent default states


  • Many of the suggestions made in this review point to changes in the URDF. This is unfortunately not the intention of the SRDF. We currently would like to separate the semantic information from the information in the URDF, hence a new format.

Wiki: srdf/review (last edited 2011-12-05 12:48:53 by Ioan Sucan)