feat(schema): define database entry for hardware (#405)

Author: eeberhard

docs/static/schemas/draft/2-1-0/application.schema.json

@@ -696,9 +696,12 @@
           "type": "object",
           "additionalProperties": false,
           "properties": {
+            "database_entry": {
+              "$ref": "#/$defs/database_entry"
+            },
             "urdf": {
               "title": "URDF",
-              "description": "The path to the URDF file of the hardware",
+              "description": "The URDF describing the hardware",
               "type": "string"
             },
             "rate": {
@@ -884,8 +887,29 @@
             }
           },
           "required": [
-            "urdf",
             "rate"
+          ],
+          "oneOf": [
+            {
+              "required": [
+                "database_entry"
+              ],
+              "not": {
+                "required": [
+                  "urdf"
+                ]
+              }
+            },
+            {
+              "required": [
+                "urdf"
+              ],
+              "not": {
+                "required": [
+                  "database_entry"
+                ]
+              }
+            }
           ]
         }
       }
@@ -1441,6 +1465,33 @@
         }
       }
     },
+    "database_entry": {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "title": "Database Entry",
+      "description": "The details of a database entry",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "title": "Database ID",
+          "description": "The ID of the entry in the database",
+          "type": "string"
+        },
+        "version": {
+          "title": "Version Tag",
+          "description": "The name of a tagged version of the entry in the database. If omitted, the latest version will be used.",
+          "type": "string",
+          "examples": [
+            "v1",
+            "release-2025-01",
+            "stable"
+          ]
+        }
+      },
+      "required": [
+        "id"
+      ]
+    },
     "identifier": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
       "$comment": "The unique identifier of an application element (e.g., a component, controller, condition, or similar) formatted in lower_snake_case",

schemas/applications/CHANGELOG.md

@@ -22,6 +22,7 @@ Release Versions:
 ## Upcoming changes (draft/2-1-0)
 
 - feat: add support for variables and assignments (#386)
+- feat: define database entry for referencing hardware (#405)
 
 ## 2-0-6
 

schemas/applications/schema/application.schema.json

@@ -134,6 +134,9 @@
     "condition_object": {
       "$ref": "common/condition_object.schema.json"
     },
+    "database_entry": {
+      "$ref": "common/database_entry.schema.json"
+    },
     "identifier": {
       "$ref": "common/identifier.schema.json"
     },

schemas/applications/schema/common/database_entry.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Database Entry",
+  "description": "The details of a database entry",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "title": "Database ID",
+      "description": "The ID of the entry in the database",
+      "type": "string"
+    },
+    "version": {
+      "title": "Version Tag",
+      "description": "The name of a tagged version of the entry in the database. If omitted, the latest version will be used.",
+      "type": "string",
+      "examples": [
+        "v1",
+        "release-2025-01",
+        "stable"
+      ]
+    }
+  },
+  "required": [
+    "id"
+  ]
+}

schemas/applications/schema/hardware.schema.json

@@ -11,9 +11,12 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
+        "database_entry": {
+          "$ref": "common/database_entry.schema.json"
+        },
         "urdf": {
           "title": "URDF",
-          "description": "The path to the URDF file of the hardware",
+          "description": "The URDF describing the hardware",
           "type": "string"
         },
         "rate": {
@@ -27,21 +30,21 @@
           ]
         },
         "tf_prefix": {
-            "description": "An optional TF prefix to apply to all of the links in the URDF to distinguish multiple instances of the same robot",
-            "type": "string",
-            "default": "",
-            "examples": [
-              "my_robot_",
-              "left_robot_",
-              "robot_1_"
-            ]
+          "description": "An optional TF prefix to apply to all of the links in the URDF to distinguish multiple instances of the same robot",
+          "type": "string",
+          "default": "",
+          "examples": [
+            "my_robot_",
+            "left_robot_",
+            "robot_1_"
+          ]
         },
         "reference_frame": {
-            "description": "An optional reference frame to relocate the hardware in the 3D scene. If left empty, the root link in the URDF will be used as the reference frame of the hardware instead.",
-            "type": "string",
-            "examples": [
-              "world"
-            ]
+          "description": "An optional reference frame to relocate the hardware in the 3D scene. If left empty, the root link in the URDF will be used as the reference frame of the hardware instead.",
+          "type": "string",
+          "examples": [
+            "world"
+          ]
         },
         "strict": {
           "title": "Strict Hardware",
@@ -199,8 +202,29 @@
         }
       },
       "required": [
-        "urdf",
         "rate"
+      ],
+      "oneOf": [
+        {
+          "required": [
+            "database_entry"
+          ],
+          "not": {
+            "required": [
+              "urdf"
+            ]
+          }
+        },
+        {
+          "required": [
+            "urdf"
+          ],
+          "not": {
+            "required": [
+              "database_entry"
+            ]
+          }
+        }
       ]
     }
   }