From d60eba407d1ee7694fd2d24cd4de8a8e5b1da514 Mon Sep 17 00:00:00 2001
From: David Peter <mail@david-peter.de>
Date: Mon, 5 Oct 2026 16:10:08 +0200
Subject: [PATCH] Version the JSON export schema

---
 README.md          | 8 ++++++--
 src/export/json.rs | 7 ++++++-
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index d7a5806..1032ccd 100644
--- a/README.md
+++ b/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
-`measurements` array with one object per measured run (excluding warmup runs):
+The JSON export contains a top-level `"schema_version": 2` and a `results` array with one entry
+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 |
 |:---|:---|:---|
diff --git a/src/export/json.rs b/src/export/json.rs
index 301d8e3..eb4a8ce 100644
--- a/src/export/json.rs
+++ b/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": [{