Add JSON Schema for bootspec

.editorconfig

@@ -10,15 +10,13 @@ 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
+[Cargo.lock]
+indent_size = unset
 
 [*.{diff,patch}]
 end_of_line = unset

.envrc

@@ -0,0 +1 @@
+use flake

.github/workflows/ci.yml

@@ -8,52 +8,103 @@ 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
 
   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
 
   NixFlakeCheck:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: DeterminateSystems/flake-checker-action@main
       with:
         fail-mode: false
 
   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"
 
   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
+
+  BuildAndPublishJsonSchemaDocs:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.publish.outputs.page_url }}
+    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: Set up GitHub Pages
+      uses: actions/configure-pages@v5
+    - 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
+      id: publish
+      uses: actions/deploy-pages@v4
+
   SynthesizeIntegration:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         fetch-depth: 0
     - uses: DeterminateSystems/nix-installer-action@main

.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

.gitignore

@@ -2,3 +2,6 @@
 result*
 synthesize/integration-test-cases/builds
 synthesize/integration-test-cases/generated-synthesis
+
+# Docs output
+/dist

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" ];
+      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
     {
@@ -30,6 +26,8 @@
             codespell
             nixpkgs-fmt
             rustfmt
+            jsonschema # provides the jv tool
+            json-schema-for-humans # provides the generate-schema-doc tool
           ];
         });
 
@@ -40,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);
     };
 }

schema.json

@@ -0,0 +1,87 @@
+{
+  "$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": "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": {
+      "type": "object",
+      "patternProperties": {
+        "^.*$": {
+          "type": "object",
+          "properties": {
+            "org.nixos.bootspec.v1": { "$ref": "#/$defs/Bootspec" }
+          },
+          "required": ["org.nixos.bootspec.v1"],
+          "additionalProperties": true
+        }
+      }
+    }
+  },
+  "patternProperties": {
+    "^.*$": {
+      "$ref": "#/$defs/Bootspec",
+      "description": "Testing"
+    }
+  },
+  "$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."
+        }
+      }
+    }
+  }
+}