From b979877914c09445b600a88f01eea9c5de0360b8 Mon Sep 17 00:00:00 2001
From: Steve Peters <scpeters@openrobotics.org>
Date: Tue, 27 Feb 2024 15:23:44 -0800
Subject: [PATCH 1/6] Spec 1.12: add _state suffix to state subelements

Signed-off-by: Steve Peters <scpeters@openrobotics.org>
---
 sdf/1.12/light_state.sdf         |  2 +-
 sdf/1.12/link_state.sdf          |  4 +--
 sdf/1.12/model_state.sdf         |  6 ++--
 test/integration/frame.cc        | 24 +++++++-------
 test/integration/nested_model.cc | 57 +++++++++++++++++---------------
 5 files changed, 48 insertions(+), 45 deletions(-)

diff --git a/sdf/1.12/light_state.sdf b/sdf/1.12/light_state.sdf
index 673efcdb4..b0e02da86 100644
--- a/sdf/1.12/light_state.sdf
+++ b/sdf/1.12/light_state.sdf
@@ -1,5 +1,5 @@
 <!-- State information for a light -->
-<element name="light" required="*">
+<element name="light_state" required="*">
   <description>Light state</description>
 
   <attribute name="name" type="string" default="__default__" required="1">
diff --git a/sdf/1.12/link_state.sdf b/sdf/1.12/link_state.sdf
index 28fff465d..a04c8f66f 100644
--- a/sdf/1.12/link_state.sdf
+++ b/sdf/1.12/link_state.sdf
@@ -1,5 +1,5 @@
 <!-- State information for a link -->
-<element name="link" required="*">
+<element name="link_state" required="*">
   <description>Link state</description>
 
   <attribute name="name" type="string" default="__default__" required="1">
@@ -27,7 +27,7 @@
     </description>
   </element>
 
-  <element name="collision" required="*">
+  <element name="collision_state" required="*">
     <description>Collision state</description>
 
     <attribute name="name" type="string" default="__default__" required="1">
diff --git a/sdf/1.12/model_state.sdf b/sdf/1.12/model_state.sdf
index 3fd296ff2..9a021040d 100644
--- a/sdf/1.12/model_state.sdf
+++ b/sdf/1.12/model_state.sdf
@@ -1,12 +1,12 @@
 <!-- State information for a model -->
-<element name="model" required="*">
+<element name="model_state" required="*">
   <description>Model state</description>
 
   <attribute name="name" type="string" default="__default__" required="1">
     <description>Name of the model</description>
   </attribute>
 
-  <element name="joint" required="*">
+  <element name="joint_state" required="*">
     <description>Joint angle</description>
 
     <attribute name="name" type="string" default="__default__" required="1">
@@ -22,7 +22,7 @@
     </element>
   </element>
 
-  <element name="model" ref="model_state" required="*">
+  <element name="model_state" ref="model_state" required="*">
     <description>A nested model state element</description>
     <attribute name="name" type="string" default="__default__" required="1">
       <description>Name of the model. </description>
diff --git a/test/integration/frame.cc b/test/integration/frame.cc
index 1ed67cd3a..b080ae5d5 100644
--- a/test/integration/frame.cc
+++ b/test/integration/frame.cc
@@ -213,18 +213,18 @@ TEST(Frame, StateFrame)
   sdfStr << "<sdf version ='" << SDF_VERSION << "'>"
     << "<world name='default'>"
     << "<state world_name='default'>"
-    << "<model name='my_model'>"
+    << "<model_state name='my_model'>"
     << "  <frame name='mframe'>"
     << "    <pose relative_to='/world'>1 0 2 0 0 0</pose>"
     << "  </frame>"
     << "  <pose relative_to='mframe'>3 3 9 0 0 0</pose>"
-    << "  <link name='my_link'>"
+    << "  <link_state name='my_link'>"
     << "    <pose relative_to='lframe'>111 3 0 0 0 0</pose>"
-    << "  </link>"
-    << "</model>"
-    << "<light name='my_light'>"
+    << "  </link_state>"
+    << "</model_state>"
+    << "<light_state name='my_light'>"
     << "    <pose relative_to='lframe'>99 0 22 0 0 0</pose>"
-    << "</light>"
+    << "</light_state>"
     << "</state>"
     << "</world>"
     << "</sdf>";
@@ -239,8 +239,8 @@ TEST(Frame, StateFrame)
   EXPECT_TRUE(worldElem->HasElement("state"));
   sdf::ElementPtr stateElem = worldElem->GetElement("state");
 
-  EXPECT_TRUE(stateElem->HasElement("model"));
-  sdf::ElementPtr modelStateElem = stateElem->GetElement("model");
+  EXPECT_TRUE(stateElem->HasElement("model_state"));
+  sdf::ElementPtr modelStateElem = stateElem->GetElement("model_state");
 
   // model
   EXPECT_TRUE(modelStateElem->HasAttribute("name"));
@@ -271,8 +271,8 @@ TEST(Frame, StateFrame)
   }
 
   // link
-  EXPECT_TRUE(modelStateElem->HasElement("link"));
-  sdf::ElementPtr linkStateElem = modelStateElem->GetElement("link");
+  EXPECT_TRUE(modelStateElem->HasElement("link_state"));
+  sdf::ElementPtr linkStateElem = modelStateElem->GetElement("link_state");
   EXPECT_TRUE(linkStateElem->HasAttribute("name"));
   EXPECT_EQ(linkStateElem->Get<std::string>("name"), "my_link");
 
@@ -286,8 +286,8 @@ TEST(Frame, StateFrame)
               gz::math::Pose3d(111, 3, 0, 0, 0, 0));
   }
 
-  EXPECT_TRUE(stateElem->HasElement("light"));
-  sdf::ElementPtr lightStateElem = stateElem->GetElement("light");
+  EXPECT_TRUE(stateElem->HasElement("light_state"));
+  sdf::ElementPtr lightStateElem = stateElem->GetElement("light_state");
 
   // light
   EXPECT_TRUE(lightStateElem->HasAttribute("name"));
diff --git a/test/integration/nested_model.cc b/test/integration/nested_model.cc
index 0c63cbc43..813d04021 100644
--- a/test/integration/nested_model.cc
+++ b/test/integration/nested_model.cc
@@ -114,33 +114,33 @@ TEST(NestedModel, State)
   sdfStr << "<sdf version ='" << SDF_VERSION << "'>"
     << "<world name='default'>"
     << "<state world_name='default'>"
-    << "<model name='model_00'>"
+    << "<model_state name='model_00'>"
     << "  <pose>0 0 0.5 0 0 0</pose>"
-    << "  <link name='link_00'>"
+    << "  <link_state name='link_00'>"
     << "    <pose>0 0 0.5 0 0 0</pose>"
     << "    <velocity>0.001 0 0 0 0 0</velocity>"
     << "    <acceleration>0 0.006121 0 0.012288 0 0.001751</acceleration>"
     << "    <wrench>0 0.006121 0 0 0 0</wrench>"
-    << "  </link>"
-    << "  <model name='model_01'>"
+    << "  </link_state>"
+    << "  <model_state name='model_01'>"
     << "    <pose>1 0 0.5 0 0 0</pose>"
-    << "    <link name='link_01'>"
+    << "    <link_state name='link_01'>"
     << "      <pose>1.25 0 0.5 0 0 0</pose>"
     << "      <velocity>0 -0.001 0 0 0 0</velocity>"
     << "      <acceleration>0 0.000674 0 -0.001268 0 0</acceleration>"
     << "      <wrench>0 0.000674 0 0 0 0</wrench>"
-    << "    </link>"
-    << "    <model name='model_02'>"
+    << "    </link_state>"
+    << "    <model_state name='model_02'>"
     << "      <pose>1 1 0.5 0 0 0</pose>"
-    << "      <link name='link_02'>"
+    << "      <link_state name='link_02'>"
     << "        <pose>1.25 1 0.5 0 0 0</pose>"
     << "        <velocity>0 0 0.001 0 0 0</velocity>"
     << "        <acceleration>0 0 0 0 0 0</acceleration>"
     << "        <wrench>0 0 0 0 0 0</wrench>"
-    << "      </link>"
-    << "    </model>"
-    << "  </model>"
-    << "</model>"
+    << "      </link_state>"
+    << "    </model_state>"
+    << "  </model_state>"
+    << "</model_state>"
     << "</state>"
     << "</world>"
     << "</sdf>";
@@ -154,9 +154,9 @@ TEST(NestedModel, State)
   sdf::ElementPtr worldElem = sdfParsed->Root()->GetElement("world");
   EXPECT_TRUE(worldElem->HasElement("state"));
   sdf::ElementPtr stateElem = worldElem->GetElement("state");
-  EXPECT_TRUE(stateElem->HasElement("model"));
+  EXPECT_TRUE(stateElem->HasElement("model_state"));
 
-  sdf::ElementPtr modelStateElem = stateElem->GetElement("model");
+  sdf::ElementPtr modelStateElem = stateElem->GetElement("model_state");
 
   // model sdf
   EXPECT_TRUE(modelStateElem->HasAttribute("name"));
@@ -164,11 +164,12 @@ TEST(NestedModel, State)
   EXPECT_TRUE(modelStateElem->HasElement("pose"));
   EXPECT_EQ(modelStateElem->Get<gz::math::Pose3d>("pose"),
     gz::math::Pose3d(0, 0, 0.5, 0, 0, 0));
-  EXPECT_TRUE(!modelStateElem->HasElement("joint"));
+  EXPECT_FALSE(modelStateElem->HasElement("joint"));
+  EXPECT_FALSE(modelStateElem->HasElement("joint_state"));
 
   // link sdf
-  EXPECT_TRUE(modelStateElem->HasElement("link"));
-  sdf::ElementPtr linkStateElem = modelStateElem->GetElement("link");
+  EXPECT_TRUE(modelStateElem->HasElement("link_state"));
+  sdf::ElementPtr linkStateElem = modelStateElem->GetElement("link_state");
   EXPECT_TRUE(linkStateElem->HasAttribute("name"));
   EXPECT_EQ(linkStateElem->Get<std::string>("name"), "link_00");
   EXPECT_TRUE(linkStateElem->HasElement("pose"));
@@ -185,20 +186,21 @@ TEST(NestedModel, State)
     gz::math::Pose3d(0, 0.006121, 0, 0, 0, 0));
 
   // nested model sdf
-  EXPECT_TRUE(modelStateElem->HasElement("model"));
+  EXPECT_TRUE(modelStateElem->HasElement("model_state"));
   sdf::ElementPtr nestedModelStateElem =
-    modelStateElem->GetElement("model");
+    modelStateElem->GetElement("model_state");
   EXPECT_TRUE(nestedModelStateElem->HasAttribute("name"));
   EXPECT_EQ(nestedModelStateElem->Get<std::string>("name"), "model_01");
   EXPECT_TRUE(nestedModelStateElem->HasElement("pose"));
   EXPECT_EQ(nestedModelStateElem->Get<gz::math::Pose3d>("pose"),
     gz::math::Pose3d(1, 0, 0.5, 0, 0, 0));
-  EXPECT_TRUE(!nestedModelStateElem->HasElement("joint"));
+  EXPECT_FALSE(nestedModelStateElem->HasElement("joint"));
+  EXPECT_FALSE(nestedModelStateElem->HasElement("joint_state"));
 
   // nested model's link sdf
-  EXPECT_TRUE(nestedModelStateElem->HasElement("link"));
+  EXPECT_TRUE(nestedModelStateElem->HasElement("link_state"));
   sdf::ElementPtr nestedLinkStateElem =
-    nestedModelStateElem->GetElement("link");
+    nestedModelStateElem->GetElement("link_state");
   EXPECT_TRUE(nestedLinkStateElem->HasAttribute("name"));
   EXPECT_EQ(nestedLinkStateElem->Get<std::string>("name"), "link_01");
   EXPECT_TRUE(nestedLinkStateElem->HasElement("pose"));
@@ -215,18 +217,19 @@ TEST(NestedModel, State)
     gz::math::Pose3d(0, 0.000674, 0, 0, 0, 0));
 
   // double nested model sdf
-  EXPECT_TRUE(nestedModelStateElem->HasElement("model"));
-  nestedModelStateElem = nestedModelStateElem->GetElement("model");
+  EXPECT_TRUE(nestedModelStateElem->HasElement("model_state"));
+  nestedModelStateElem = nestedModelStateElem->GetElement("model_state");
   EXPECT_TRUE(nestedModelStateElem->HasAttribute("name"));
   EXPECT_EQ(nestedModelStateElem->Get<std::string>("name"), "model_02");
   EXPECT_TRUE(nestedModelStateElem->HasElement("pose"));
   EXPECT_EQ(nestedModelStateElem->Get<gz::math::Pose3d>("pose"),
     gz::math::Pose3d(1, 1, 0.5, 0, 0, 0));
-  EXPECT_TRUE(!nestedModelStateElem->HasElement("joint"));
+  EXPECT_FALSE(nestedModelStateElem->HasElement("joint"));
+  EXPECT_FALSE(nestedModelStateElem->HasElement("joint_state"));
 
   // double nested model's link sdf
-  EXPECT_TRUE(nestedModelStateElem->HasElement("link"));
-  nestedLinkStateElem = nestedModelStateElem->GetElement("link");
+  EXPECT_TRUE(nestedModelStateElem->HasElement("link_state"));
+  nestedLinkStateElem = nestedModelStateElem->GetElement("link_state");
   EXPECT_TRUE(nestedLinkStateElem->HasAttribute("name"));
   EXPECT_EQ(nestedLinkStateElem->Get<std::string>("name"), "link_02");
   EXPECT_TRUE(nestedLinkStateElem->HasElement("pose"));

From f5d257167590159078f8647b61fe929e52643a29 Mon Sep 17 00:00:00 2001
From: Steve Peters <scpeters@openrobotics.org>
Date: Sat, 6 Jul 2024 23:01:21 -0700
Subject: [PATCH 2/6] Define //joint_state in joint_state.sdf

Include joint_state.sdf from model_state.sdf
and state.sdf for //world/joint states.

Signed-off-by: Steve Peters <scpeters@openrobotics.org>
---
 sdf/1.12/CMakeLists.txt  |  1 +
 sdf/1.12/joint_state.sdf | 16 ++++++++++++++++
 sdf/1.12/model_state.sdf | 16 +---------------
 sdf/1.12/state.sdf       |  2 ++
 4 files changed, 20 insertions(+), 15 deletions(-)
 create mode 100644 sdf/1.12/joint_state.sdf

diff --git a/sdf/1.12/CMakeLists.txt b/sdf/1.12/CMakeLists.txt
index 08b4bf240..82d9ebf71 100644
--- a/sdf/1.12/CMakeLists.txt
+++ b/sdf/1.12/CMakeLists.txt
@@ -26,6 +26,7 @@ set (sdfs
   imu.sdf
   inertial.sdf
   joint.sdf
+  joint_state.sdf
   lidar.sdf
   light.sdf
   light_state.sdf
diff --git a/sdf/1.12/joint_state.sdf b/sdf/1.12/joint_state.sdf
new file mode 100644
index 000000000..60273b27f
--- /dev/null
+++ b/sdf/1.12/joint_state.sdf
@@ -0,0 +1,16 @@
+<!-- State information for a joint -->
+<element name="joint_state" required="*">
+  <description>Joint angle</description>
+
+  <attribute name="name" type="string" default="__default__" required="1">
+    <description>Name of the joint</description>
+  </attribute>
+
+  <element name="angle" type="double" default="0" required="+">
+    <attribute name="axis" type="unsigned int" default="0" required="1">
+      <description>Index of the axis.</description>
+    </attribute>
+
+    <description>Angle of an axis</description>
+  </element>
+</element> <!-- End Joint -->
diff --git a/sdf/1.12/model_state.sdf b/sdf/1.12/model_state.sdf
index 9a021040d..e9905621b 100644
--- a/sdf/1.12/model_state.sdf
+++ b/sdf/1.12/model_state.sdf
@@ -6,21 +6,7 @@
     <description>Name of the model</description>
   </attribute>
 
-  <element name="joint_state" required="*">
-    <description>Joint angle</description>
-
-    <attribute name="name" type="string" default="__default__" required="1">
-      <description>Name of the joint</description>
-    </attribute>
-
-    <element name="angle" type="double" default="0" required="+">
-      <attribute name="axis" type="unsigned int" default="0" required="1">
-        <description>Index of the axis.</description>
-      </attribute>
-
-      <description>Angle of an axis</description>
-    </element>
-  </element>
+  <include filename="joint_state.sdf" required="*"/>
 
   <element name="model_state" ref="model_state" required="*">
     <description>A nested model state element</description>
diff --git a/sdf/1.12/state.sdf b/sdf/1.12/state.sdf
index 6a13e28bf..412c83301 100644
--- a/sdf/1.12/state.sdf
+++ b/sdf/1.12/state.sdf
@@ -38,4 +38,6 @@
 
   <include filename="light_state.sdf" required="*"/>
 
+  <include filename="joint_state.sdf" required="*"/>
+
 </element> <!-- End State -->

From f84706e7667c2fbe14de1b10601d552f5cbfcd65 Mon Sep 17 00:00:00 2001
From: Steve Peters <scpeters@openrobotics.org>
Date: Sun, 7 Jul 2024 21:10:11 -0700
Subject: [PATCH 3/6] Update Migration guide

Signed-off-by: Steve Peters <scpeters@openrobotics.org>
---
 Migration.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/Migration.md b/Migration.md
index 410c4931b..502cfecc6 100644
--- a/Migration.md
+++ b/Migration.md
@@ -596,6 +596,22 @@ ABI was broken for `sdf::Element`, and restored on version 11.2.1.
 
 ## SDFormat specification 1.11 to 1.12
 
+### Modifications
+
+1. **state.sdf**, **model_state.sdf**, **joint_state.sdf**, **link_state.sdf**,
+   **light_state.sdf**: A `_state` suffix has been added to state element names
+   to match the `.sdf` file names and for consistency.
+    + `//state/light` renamed to `//state/light_state`
+    + `//state/model` renamed to `//state/model_state`
+    + `//state/model/joint` renamed to `//state/model_state/joint_state`
+    + `//state/model/light` renamed to `//state/model_state/light_state`
+    + `//state/model/link`  renamed to `//state/model_state/link_state`
+    + `//state/model/model` renamed to `//state/model_state/model_state`
+    + `//state/model/link/collision` renamed to `//state/model_state/link_state/collision_state`
+
+ 1. `//state/joint_state` has been added to represent the state of a
+    `//world/joint`.
+
 ## SDFormat specification 1.10 to 1.11
 
 ### Additions

From 9af611980df80f3602261467e8b9eec148114854 Mon Sep 17 00:00:00 2001
From: Steve Peters <scpeters@openrobotics.org>
Date: Fri, 19 Jul 2024 17:19:08 -0700
Subject: [PATCH 4/6] update migration guide

Signed-off-by: Steve Peters <scpeters@openrobotics.org>
---
 Migration.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Migration.md b/Migration.md
index 5eb01d511..6aa6e465f 100644
--- a/Migration.md
+++ b/Migration.md
@@ -641,7 +641,7 @@ ABI was broken for `sdf::Element`, and restored on version 11.2.1.
     + `//state/model/model` renamed to `//state/model_state/model_state`
     + `//state/model/link/collision` renamed to `//state/model_state/link_state/collision_state`
 
- 1. `//state/joint_state` has been added to represent the state of a
+1. **state.sdf**: `//state/joint_state` has been added to represent the state of a
     `//world/joint`.
 
 ## SDFormat specification 1.10 to 1.11

From 33d66341cfa1f8691c6512906533131d1200f130 Mon Sep 17 00:00:00 2001
From: Steve Peters <scpeters@openrobotics.org>
Date: Tue, 13 Aug 2024 18:07:53 -0700
Subject: [PATCH 5/6] Allow joints in //state/insertions

Signed-off-by: Steve Peters <scpeters@openrobotics.org>
---
 Migration.md       | 3 ++-
 sdf/1.12/state.sdf | 1 +
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/Migration.md b/Migration.md
index 6aa6e465f..341816cf2 100644
--- a/Migration.md
+++ b/Migration.md
@@ -642,7 +642,8 @@ ABI was broken for `sdf::Element`, and restored on version 11.2.1.
     + `//state/model/link/collision` renamed to `//state/model_state/link_state/collision_state`
 
 1. **state.sdf**: `//state/joint_state` has been added to represent the state of a
-    `//world/joint`.
+    `//world/joint` and `//state/insertions/joint` can represent inserted
+    `//world/joint` elements.
 
 ## SDFormat specification 1.10 to 1.11
 
diff --git a/sdf/1.12/state.sdf b/sdf/1.12/state.sdf
index 412c83301..a7d2d471f 100644
--- a/sdf/1.12/state.sdf
+++ b/sdf/1.12/state.sdf
@@ -25,6 +25,7 @@
     <description>A list containing the entire description of entities inserted.</description>
     <include filename="model.sdf" required="+"/>
     <include filename="light.sdf" required="+"/>
+    <include filename="joint.sdf" required="+"/>
   </element>
 
   <element name="deletions" required="0">

From cd32f6e8a178860649c62327be661b86b199f117 Mon Sep 17 00:00:00 2001
From: Steve Peters <scpeters@openrobotics.org>
Date: Tue, 13 Aug 2024 18:10:38 -0700
Subject: [PATCH 6/6] Improve description of state elements

Signed-off-by: Steve Peters <scpeters@openrobotics.org>
---
 sdf/1.12/joint_state.sdf |  5 ++++-
 sdf/1.12/light_state.sdf |  5 ++++-
 sdf/1.12/link_state.sdf  |  6 +++++-
 sdf/1.12/model_state.sdf |  6 +++++-
 sdf/1.12/state.sdf       | 11 +++++++++--
 5 files changed, 27 insertions(+), 6 deletions(-)

diff --git a/sdf/1.12/joint_state.sdf b/sdf/1.12/joint_state.sdf
index 60273b27f..2b64d832c 100644
--- a/sdf/1.12/joint_state.sdf
+++ b/sdf/1.12/joint_state.sdf
@@ -1,6 +1,9 @@
 <!-- State information for a joint -->
 <element name="joint_state" required="*">
-  <description>Joint angle</description>
+  <description>
+    The joint state element encapsulates variables within a joint that may
+    change over time, currently limited to the joint angle.
+  </description>
 
   <attribute name="name" type="string" default="__default__" required="1">
     <description>Name of the joint</description>
diff --git a/sdf/1.12/light_state.sdf b/sdf/1.12/light_state.sdf
index b0e02da86..54bebb02f 100644
--- a/sdf/1.12/light_state.sdf
+++ b/sdf/1.12/light_state.sdf
@@ -1,6 +1,9 @@
 <!-- State information for a light -->
 <element name="light_state" required="*">
-  <description>Light state</description>
+  <description>
+    The light state element encapsulates variables within a light that may
+    change over time, currently limited to its pose.
+  </description>
 
   <attribute name="name" type="string" default="__default__" required="1">
     <description>Name of the light</description>
diff --git a/sdf/1.12/link_state.sdf b/sdf/1.12/link_state.sdf
index a04c8f66f..e59d9e0f1 100644
--- a/sdf/1.12/link_state.sdf
+++ b/sdf/1.12/link_state.sdf
@@ -1,6 +1,10 @@
 <!-- State information for a link -->
 <element name="link_state" required="*">
-  <description>Link state</description>
+  <description>
+    The link state element encapsulates variables within a link that may
+    change over time, including pose, velocity, acceleration, applied wrench,
+    and the state of attached collisions.
+  </description>
 
   <attribute name="name" type="string" default="__default__" required="1">
     <description>Name of the link</description>
diff --git a/sdf/1.12/model_state.sdf b/sdf/1.12/model_state.sdf
index e9905621b..cbbbfd0de 100644
--- a/sdf/1.12/model_state.sdf
+++ b/sdf/1.12/model_state.sdf
@@ -1,6 +1,10 @@
 <!-- State information for a model -->
 <element name="model_state" required="*">
-  <description>Model state</description>
+  <description>
+    The model state element encapsulates variables within a model that may
+    change over time, including object poses, the states of its nested models
+    and links and joints, and changes in model scale.
+  </description>
 
   <attribute name="name" type="string" default="__default__" required="1">
     <description>Name of the model</description>
diff --git a/sdf/1.12/state.sdf b/sdf/1.12/state.sdf
index a7d2d471f..30fbd4e42 100644
--- a/sdf/1.12/state.sdf
+++ b/sdf/1.12/state.sdf
@@ -1,5 +1,12 @@
 <!-- State Info -->
 <element name="state" required="*">
+  <description>
+    The state element encapsulates variables within a world that may change
+    over time, including object poses, dynamic states such as velocity and
+    acceleration, a description of objects added to the world, and a list
+    of objects deleted from the world.
+  </description>
+
   <!-- Name of the world this state applies to -->
   <attribute name="world_name" type="string" default="__default__" required="1">
     <description>Name of the world this state applies to</description>
@@ -22,14 +29,14 @@
   </element>
 
   <element name="insertions" required="0">
-    <description>A list containing the entire description of entities inserted.</description>
+    <description>A list containing the entire description of entities inserted into the world.</description>
     <include filename="model.sdf" required="+"/>
     <include filename="light.sdf" required="+"/>
     <include filename="joint.sdf" required="+"/>
   </element>
 
   <element name="deletions" required="0">
-    <description>A list of names of deleted entities/</description>
+    <description>A list of names of entities deleted from the world./</description>
     <element name="name" type="string" default="__default__" required="+">
       <description>The name of a deleted entity.</description>
     </element>