From 372818a7d6b5e7a94ab7112e776b8a5c0d10a010 Mon Sep 17 00:00:00 2001
From: Luc Perkins <lucperkins@gmail.com>
Date: Tue, 22 Apr 2025 16:21:43 -0300
Subject: [PATCH 1/7] Add initial bootspec schema

---
 .editorconfig                |  7 +--
 .envrc                       |  1 +
 .github/workflows/ci.yml     | 32 +++++++++++---
 .github/workflows/update.yml |  4 +-
 flake.nix                    |  3 +-
 schema.json                  | 83 ++++++++++++++++++++++++++++++++++++
 6 files changed, 116 insertions(+), 14 deletions(-)
 create mode 100644 .envrc
 create mode 100644 schema.json

diff --git a/.editorconfig b/.editorconfig
index dbc08ec..284b7b2 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -10,16 +10,11 @@ end_of_line = lf
 insert_final_newline = true
 trim_trailing_whitespace = true
 indent_style = space
+indent_size = 2
 
 [*.rs]
 indent_size = 4
 
-[*.toml]
-indent_size = 2
-
-[*.nix]
-indent_size = 2
-
 [*.{diff,patch}]
 end_of_line = unset
 insert_final_newline = unset
diff --git a/.envrc b/.envrc
new file mode 100644
index 0000000..3550a30
--- /dev/null
+++ b/.envrc
@@ -0,0 +1 @@
+use flake
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 2bb54ca..7fa4a01 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -8,8 +8,10 @@ jobs:
   format:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: DeterminateSystems/nix-installer-action@main
+      with:
+        determinate: true
     - uses: DeterminateSystems/flakehub-cache-action@main
     - name: Check rustfmt
       run: nix develop --command cargo fmt -- --check
@@ -17,8 +19,10 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: DeterminateSystems/nix-installer-action@main
+      with:
+        determinate: true
     - uses: DeterminateSystems/flakehub-cache-action@main
     - name: Build
       run: nix build -L
@@ -26,7 +30,7 @@ jobs:
   NixFlakeCheck:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: DeterminateSystems/flake-checker-action@main
       with:
         fail-mode: false
@@ -34,10 +38,12 @@ jobs:
   NixFormatting:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         fetch-depth: 0
     - uses: DeterminateSystems/nix-installer-action@main
+      with:
+        determinate: true
     - uses: DeterminateSystems/flakehub-cache-action@main
     - name: Check nixpkgs-fmt formatting
       run: nix develop --command sh -c "git ls-files '*.nix' | xargs nixpkgs-fmt --check"
@@ -45,15 +51,29 @@ jobs:
   EditorConfig:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - uses: greut/eclint-action@v0
 
+  ValidateJsonSchema:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - uses: DeterminateSystems/nix-installer-action@main
+      with:
+        determinate: true
+    - uses: DeterminateSystems/flakehub-cache-action@main
+    - name: Validate JSON Schema
+      run: nix develop --command jv ./schema.json
+
+
   SynthesizeIntegration:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         fetch-depth: 0
     - uses: DeterminateSystems/nix-installer-action@main
diff --git a/.github/workflows/update.yml b/.github/workflows/update.yml
index 3dea50a..b854281 100644
--- a/.github/workflows/update.yml
+++ b/.github/workflows/update.yml
@@ -9,13 +9,15 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Check flake
         uses: DeterminateSystems/flake-checker-action
         with:
           fail-mode: true
       - name: Install Nix
         uses: DeterminateSystems/nix-installer-action@main
+        with:
+          determinate: true
       - name: Enable FlakeHub cache
         uses: DeterminateSystems/flakehub-cache-action@main
       - name: Update flake.lock
diff --git a/flake.nix b/flake.nix
index 901a297..7fc5590 100644
--- a/flake.nix
+++ b/flake.nix
@@ -11,7 +11,7 @@
     let
       nameValuePair = name: value: { inherit name value; };
       genAttrs = names: f: builtins.listToAttrs (map (n: nameValuePair n (f n)) names);
-      allSystems = [ "x86_64-linux" "aarch64-linux" "i686-linux" "x86_64-darwin" ];
+      allSystems = [ "x86_64-linux" "aarch64-linux" "i686-linux" "x86_64-darwin" "aarch64-darwin" ];
 
       forAllSystems = f: genAttrs allSystems (system: f {
         inherit system;
@@ -30,6 +30,7 @@
             codespell
             nixpkgs-fmt
             rustfmt
+            jsonschema # provides the jv tool
           ];
         });
 
diff --git a/schema.json b/schema.json
new file mode 100644
index 0000000..540c5be
--- /dev/null
+++ b/schema.json
@@ -0,0 +1,83 @@
+{
+  "$id": "https://raw.githubusercontent.com/DeterminateSystems/bootspec/v1.0.0/schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "NixOS bootspec v1 schema",
+  "description": "TODO",
+  "type": "object",
+  "properties": {
+    "org.nixos.bootspec.v1": { "$ref": "#/$defs/Bootspec" },
+    "org.nixos.specialisation.v1": {
+      "type": "object",
+      "patternProperties": {
+        "^.*$": {
+          "type": "object",
+          "properties": {
+            "org.nixos.bootspec.v1": { "$ref": "#/$defs/Bootspec" }
+          },
+          "required": ["org.nixos.bootspec.v1"],
+          "additionalProperties": true
+        }
+      }
+    }
+  },
+  "patternProperties": {
+    "^.*$": { "$ref": "#/$defs/Bootspec" }
+  },
+  "$defs": {
+    "Bootspec": {
+      "type": "object",
+      "required": ["init", "kernel", "kernelParams", "label", "system", "toplevel"],
+      "properties": {
+        "init": {
+          "type": "string",
+          "description": "Nix store path to the stage-2 init, executed by initrd (if present)."
+        },
+        "kernel": {
+          "type": "string",
+          "description": "Nix store path to the kernel image."
+        },
+        "kernelParams": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Kernel command line options.",
+          "examples": [
+            [
+            "amd_iommu=on",
+            "amd_iommu=pt",
+            "iommu=pt",
+            "kvm.ignore_msrs=1",
+            "kvm.report_ignored_msrs=0",
+            "udev.log_priority=3",
+            "systemd.unified_cgroup_hierarchy=1",
+            "loglevel=4"
+            ]
+          ]
+        },
+        "label": {
+          "type": "string",
+          "description": "A human-readable label for the system. It should contain the operating system, kernel version,and other user-relevant information to identify the system. This corresponds loosely to `config.system.nixos.label`.",
+          "examples": ["NixOS 21.11.20210810.dirty (Linux 5.15.30)"]
+        },
+        "system": {
+          "type": "string",
+          "description": "Nix system type the bootspec is intended for.",
+          "examples": ["x86_64-linux", "aarch64-linux"]
+        },
+        "toplevel": {
+          "type": "string",
+          "description": "Top-level Nix store path of the system closure."
+        },
+        "initrd": {
+          "type": "string",
+          "description": "Nix store path to the initrd."
+        },
+        "initrdSecrets": {
+          "type": "string",
+          "description": "Nix store path to a tool that dynamically adds secrets to initrd. Consumers of a bootspec document should copy the file referenced by the `initrd` key to a writable location, ensure that the file is writable, invoke this tool with the path to the initrd as its only argument, and use the initrd as modified by the tool for booting. This may be used to add files from outside the Nix store to the initrd. This tool is expected to run on the system whose boot specification is being set up, and may thus fail if used on a system where the expected stateful files are not in place or whose CPU does not support the instruction set of the system to be booted. If this field is present and the tool fails, no boot configuration should be generated for the system."
+        }
+      }
+    }
+  }
+}

From 6a00b800ea3eb820387c6c7f66b4d46ef7d3b6f8 Mon Sep 17 00:00:00 2001
From: Luc Perkins <lucperkins@gmail.com>
Date: Tue, 22 Apr 2025 16:34:37 -0300
Subject: [PATCH 2/7] Update docs to GitHub Pages

---
 .github/workflows/ci.yml | 27 +++++++++++++++++++++++++++
 .gitignore               |  3 +++
 flake.nix                |  1 +
 3 files changed, 31 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 7fa4a01..1a5d81f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -69,6 +69,33 @@ jobs:
     - name: Validate JSON Schema
       run: nix develop --command jv ./schema.json
 
+  PublishJsonSchemaDocs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - uses: DeterminateSystems/nix-installer-action@main
+      with:
+        determinate: true
+    - uses: DeterminateSystems/flakehub-cache-action@main
+    - name: Generate JSON Schema docs
+      id: generate
+      run: |
+        mkdir -p dist
+        nix develop --command generate-schema-doc --config expand_buttons=true schema.json dist/index.html
+    - name: Upload docs
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: ./dist
+    - name: Publish docs to GitHub Pages
+      uses: actions/deploy-pages@v4
+      with:
+        artifact_name: bootspec-json-schema-docs
 
   SynthesizeIntegration:
     runs-on: ubuntu-latest
diff --git a/.gitignore b/.gitignore
index 4543ea8..b05dbce 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,6 @@
 result*
 synthesize/integration-test-cases/builds
 synthesize/integration-test-cases/generated-synthesis
+
+# Docs output
+/dist
diff --git a/flake.nix b/flake.nix
index 7fc5590..9f5c5dd 100644
--- a/flake.nix
+++ b/flake.nix
@@ -31,6 +31,7 @@
             nixpkgs-fmt
             rustfmt
             jsonschema # provides the jv tool
+            json-schema-for-humans # provides the generate-schema-doc tool
           ];
         });
 

From 06894379524ce88955f8921b602f0c9d93fe440b Mon Sep 17 00:00:00 2001
From: Luc Perkins <lucperkins@gmail.com>
Date: Tue, 22 Apr 2025 16:40:18 -0300
Subject: [PATCH 3/7] Add more doc descriptions and fix flake

---
 flake.nix   | 14 +++++---------
 schema.json |  7 +++++--
 2 files changed, 10 insertions(+), 11 deletions(-)

diff --git a/flake.nix b/flake.nix
index 9f5c5dd..235dac8 100644
--- a/flake.nix
+++ b/flake.nix
@@ -3,19 +3,15 @@
 
   inputs.nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
 
-  outputs =
-    { self
-    , nixpkgs
-    , ...
-    } @ inputs:
+  outputs = inputs:
     let
       nameValuePair = name: value: { inherit name value; };
       genAttrs = names: f: builtins.listToAttrs (map (n: nameValuePair n (f n)) names);
-      allSystems = [ "x86_64-linux" "aarch64-linux" "i686-linux" "x86_64-darwin" "aarch64-darwin" ];
+      allSystems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
 
       forAllSystems = f: genAttrs allSystems (system: f {
         inherit system;
-        pkgs = import nixpkgs { inherit system; };
+        pkgs = import inputs.nixpkgs { inherit system; };
       });
     in
     {
@@ -42,12 +38,12 @@
               pname = "bootspec";
               version = "unreleased";
 
-              src = self;
+              src = inputs.self;
 
               cargoLock.lockFile = ./Cargo.lock;
             };
           });
 
-      defaultPackage = forAllSystems ({ system, ... }: self.packages.${system}.package);
+      defaultPackage = forAllSystems ({ system, ... }: inputs.self.packages.${system}.package);
     };
 }
diff --git a/schema.json b/schema.json
index 540c5be..d5e48e4 100644
--- a/schema.json
+++ b/schema.json
@@ -2,7 +2,7 @@
   "$id": "https://raw.githubusercontent.com/DeterminateSystems/bootspec/v1.0.0/schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "NixOS bootspec v1 schema",
-  "description": "TODO",
+  "description": "Bootspec is a set of memoized facts about a system's closure. The top-level object may contain arbitrary further keys (\"extensions\") whose semantics may be defined by third parties. The use of reverse-domain-name namespacing is recommended in order to avoid name collisions.",
   "type": "object",
   "properties": {
     "org.nixos.bootspec.v1": { "$ref": "#/$defs/Bootspec" },
@@ -21,7 +21,10 @@
     }
   },
   "patternProperties": {
-    "^.*$": { "$ref": "#/$defs/Bootspec" }
+    "^.*$": {
+      "$ref": "#/$defs/Bootspec",
+      "description": "Testing"
+    }
   },
   "$defs": {
     "Bootspec": {

From f61a3ec61996e3978354fbaf5a89d89fc3d65ac4 Mon Sep 17 00:00:00 2001
From: Luc Perkins <lucperkins@gmail.com>
Date: Tue, 22 Apr 2025 16:43:03 -0300
Subject: [PATCH 4/7] Make editorconfig ignore Cargo.lock

---
 .editorconfig | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.editorconfig b/.editorconfig
index 284b7b2..7a9cf66 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -15,6 +15,9 @@ indent_size = 2
 [*.rs]
 indent_size = 4
 
+[Cargo.lock]
+indent_size = unset
+
 [*.{diff,patch}]
 end_of_line = unset
 insert_final_newline = unset

From ca80fc4450db811eda1b5d9a96570b463618fb1b Mon Sep 17 00:00:00 2001
From: Luc Perkins <lucperkins@gmail.com>
Date: Tue, 22 Apr 2025 16:46:28 -0300
Subject: [PATCH 5/7] Remove artifact name setting

---
 .github/workflows/ci.yml | 2 --
 1 file changed, 2 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1a5d81f..4e27471 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -94,8 +94,6 @@ jobs:
         path: ./dist
     - name: Publish docs to GitHub Pages
       uses: actions/deploy-pages@v4
-      with:
-        artifact_name: bootspec-json-schema-docs
 
   SynthesizeIntegration:
     runs-on: ubuntu-latest

From 7b01a259721fd9e12d573e5e83530616e581b977 Mon Sep 17 00:00:00 2001
From: Luc Perkins <lucperkins@gmail.com>
Date: Tue, 22 Apr 2025 17:21:29 -0300
Subject: [PATCH 6/7] Fix publishing job

---
 .github/workflows/ci.yml | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 4e27471..e55f802 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -69,8 +69,11 @@ jobs:
     - name: Validate JSON Schema
       run: nix develop --command jv ./schema.json
 
-  PublishJsonSchemaDocs:
+  BuildAndPublishJsonSchemaDocs:
     runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.publish.outputs.page_url }}
     permissions:
       contents: read
       pages: write
@@ -83,6 +86,8 @@ jobs:
       with:
         determinate: true
     - uses: DeterminateSystems/flakehub-cache-action@main
+    - name: Set up GitHub Pages
+      uses: actions/configure-pages@v5
     - name: Generate JSON Schema docs
       id: generate
       run: |
@@ -93,6 +98,7 @@ jobs:
       with:
         path: ./dist
     - name: Publish docs to GitHub Pages
+      id: publish
       uses: actions/deploy-pages@v4
 
   SynthesizeIntegration:

From 615e6a4f1f4dec81188712567bab7e6ea213b3b8 Mon Sep 17 00:00:00 2001
From: Luc Perkins <lucperkins@gmail.com>
Date: Tue, 22 Apr 2025 17:38:31 -0300
Subject: [PATCH 7/7] Make additional top-level keys optional

---
 schema.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/schema.json b/schema.json
index d5e48e4..6bdb62f 100644
--- a/schema.json
+++ b/schema.json
@@ -4,6 +4,7 @@
   "title": "NixOS bootspec v1 schema",
   "description": "Bootspec is a set of memoized facts about a system's closure. The top-level object may contain arbitrary further keys (\"extensions\") whose semantics may be defined by third parties. The use of reverse-domain-name namespacing is recommended in order to avoid name collisions.",
   "type": "object",
+  "required": ["org.nixos.bootspec.v1"],
   "properties": {
     "org.nixos.bootspec.v1": { "$ref": "#/$defs/Bootspec" },
     "org.nixos.specialisation.v1": {