Version the JSON export schema

README.md

@@ -158,8 +158,12 @@ You can use the `--export-markdown <file>` option to create tables like the foll
 
 #### JSON
 
-The JSON export contains a `results` array with one entry per benchmark. Each entry has a
+The JSON export contains a top-level `"schema_version": 2` and a `results` array with one entry
-`measurements` array with one object per measured run (excluding warmup runs):
+per benchmark. Earlier exports without `schema_version` use the legacy format (version 1).
+The schema version is independent of the hyperfine release version and changes when the format
+changes incompatibly; adding optional metrics does not require a new schema version.
+
+Each result has a `measurements` array with one object per measured run (excluding warmup runs):
 
 | Field | Format | Meaning and platform differences |
 |:---|:---|:---|

src/export/json.rs

@@ -10,6 +10,7 @@ use anyhow::Result;
 
 #[derive(Serialize, Debug)]
 struct HyperfineSummary<'a> {
+    schema_version: u32,
     results: &'a [BenchmarkResult],
 }
 
@@ -24,7 +25,10 @@ impl Exporter for JsonExporter {
         _sort_order: SortOrder,
         _reference_index: Option<usize>,
     ) -> Result<Vec<u8>> {
-        let mut output = to_vec_pretty(&HyperfineSummary { results });
+        let mut output = to_vec_pretty(&HyperfineSummary {
+            schema_version: 2,
+            results,
+        });
         if let Ok(ref mut content) = output {
             content.push(b'\n');
         }
@@ -63,6 +67,7 @@ fn test_json_optional_memory() {
             .unwrap();
         let actual: serde_json::Value = serde_json::from_slice(&output).unwrap();
         let mut expected = json!({
+            "schema_version": 2,
             "results": [{
                 "command": "example",
                 "measurements": [{