diff --git a/DESCRIPTION b/DESCRIPTION
index 31a70c05..990bbff8 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: orderly2
 Title: Orderly Next Generation
-Version: 1.99.58
+Version: 1.99.59
 Authors@R: c(person("Rich", "FitzJohn", role = c("aut", "cre"),
                     email = "rich.fitzjohn@gmail.com"),
              person("Robert", "Ashton", role = "aut"),
diff --git a/inst/schema/orderly/orderly.json b/inst/schema/orderly/orderly.json
index 0b1261ca..0914bb67 100644
--- a/inst/schema/orderly/orderly.json
+++ b/inst/schema/orderly/orderly.json
@@ -6,6 +6,7 @@
     "type": "object",
     "properties": {
         "artefacts": {
+            "comment": "Artefacts are sets of (at least 1) output files that result from running a packet",
             "type": "array",
             "items": {
                 "type": "object",
@@ -40,6 +41,7 @@
             }
         },
         "role": {
+            "comment": "Assigns a 'role' (category) to input files. Any file that is not an output is considered an input.",
             "type": "array",
             "items": {
                 "type": "object",
@@ -72,7 +74,7 @@
         },
 
         "session": {
-            "description": "Information about the session",
+            "description": "Information about the session in which the packet was run",
             "type": "object",
             "properties": {
                 "platform": {
@@ -91,6 +93,7 @@
                     "required": ["version", "os", "system"]
                 },
                 "packages": {
+                    "comment": "Records metadata on the packages that were loaded during the session",  
                     "type": "array",
                     "items": {
                         "type": "object",