Move JSON format description to README.md

README.md

@@ -36,11 +36,14 @@ PSM's feature progress.
   practice: it's rather expensive to generate, so once we have a new
   version we like to keep it until the next time we regenerate.
 
+## What's here.
+
 * `get-inputs`
   Script that gathers data from various PSM project sources
   (high-level features list, requirements list, issue tracker) and
   turns it into JSON which is then used as input to the dashboard
-  display code.
+  display code.  See the "Data format" section in this document for
+  details.
 
 * `dashboard-data-sketch.txt`
   A description of the output format that `get-inputs` produces.
@@ -101,3 +104,82 @@ PSM's feature progress.
   ots-tools/github-tools/gh-sak, to put req labels on our issues.
   Those JSON files are still around on the PSM repository's archival
   rtm-issue-linking branch, but we haven't preserved them here.
+
+## Data format
+
+This is the JSON data input format that the dashboard expects:
+
+      "features": {
+        "psm-feature-000": {
+          "description": String,
+          "status": String ["Complete", "InProgress", "NotStarted"],
+          "startDate": String[Date] or null,
+          "completedDate": String[Date] or null,
+          "requirements": [
+            "psm-FR-8.2", 
+            "psm-FR-8.3", 
+            ...
+          ]
+        },
+        "psm-feature-001": {
+          ...
+        }
+      }
+      
+
+      "requirements": {
+        "psm-FR-8.2": {
+          "description": String,
+          "status": String ["Complete", "InProgress", "NotStarted"],
+          "startDate": String[Date] or null,
+          "completedDate": String[Date] or null,
+          "issues": [
+            123,
+            456,
+            789,
+            ...
+          ]
+        },
+        "psm-FR-8.3": {
+          ...
+        },
+        ...
+      }
+
+
+      "issues": {
+        "123": {
+          "title": String,
+          "description": String,
+          "url": String,
+          "status": String ["Complete", "InProgress", "NotStarted"],
+          "startDate": String[Date] or null,
+          "completedDate": String[Date] or null,
+        },
+        "456": {
+          ...
+        },
+        ...
+      }
+
+Fields without values (e.g. startDate, or completedDate) should be
+`null` which is JSON's way of representing absence of a value:
+
+      {
+        "startDate": null
+      }
+
+And dates should be represented as strings in ISO 8601 format
+(https://www.w3.org/TR/NOTE-datetime) which can readily be converted into JS
+Date objects if needed:
+
+      {
+        "startDate": "2018-06-11"
+      }
+
+Minimum precision for dates should be the day (as above), but hours and minutes
+can also optionally be included:
+
+      {
+        "startDate": "2018-06-11T19:20+01:00"
+      }

get-inputs

@@ -51,7 +51,7 @@ Usage:
 used as a cheap kind of progress meter.  Just redirect stdout as in
 the above example to separate it from the noise on stderr.)
 
-Normal output is JSON formatted as per 'dashboard-data-sketch.txt'.
+Default output is JSON data as described in the dashboard README.md.
 However, if the '--featureless-reqs' option is passed, instead show a
 list of requirements (from the RTM) that are not associated with any
 high-level feature.  To just see usage, run with '-h' or '--help'.