Skip to content

Commit 9f2a933

Browse files
lucperkinslucperkins
authored
Add JSON Schema for bootspec (#176)
* Add initial bootspec schema * Update docs to GitHub Pages * Add more doc descriptions and fix flake * Make editorconfig ignore Cargo.lock * Remove artifact name setting * Fix publishing job
1 parent 8ed0f86 commit 9f2a933

File tree

7 files changed

+153
-21
lines changed

7 files changed

+153
-21
lines changed

‎.editorconfig‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,13 @@ end_of_line = lf
1010
insert_final_newline = true
1111
trim_trailing_whitespace = true
1212
indent_style = space
13+
indent_size = 2
1314

1415
[*.rs]
1516
indent_size = 4
1617

17-
[*.toml]
18-
indent_size = 2
19-
20-
[*.nix]
21-
indent_size = 2
18+
[Cargo.lock]
19+
indent_size = unset
2220

2321
[*.{diff,patch}]
2422
end_of_line = unset

‎.envrc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
use flake

‎.github/workflows/ci.yml‎

Lines changed: 51 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ jobs:
88
format:
99
runs-on: ubuntu-latest
1010
steps:
11-
- uses: actions/checkout@v3
11+
- uses: actions/checkout@v4
1212
- uses: DeterminateSystems/nix-installer-action@main
1313
with:
1414
determinate: true
@@ -19,7 +19,7 @@ jobs:
1919
build:
2020
runs-on: ubuntu-latest
2121
steps:
22-
- uses: actions/checkout@v3
22+
- uses: actions/checkout@v4
2323
- uses: DeterminateSystems/nix-installer-action@main
2424
with:
2525
determinate: true
@@ -30,15 +30,15 @@ jobs:
3030
NixFlakeCheck:
3131
runs-on: ubuntu-latest
3232
steps:
33-
- uses: actions/checkout@v3
33+
- uses: actions/checkout@v4
3434
- uses: DeterminateSystems/flake-checker-action@main
3535
with:
3636
fail-mode: false
3737

3838
NixFormatting:
3939
runs-on: ubuntu-latest
4040
steps:
41-
- uses: actions/checkout@v3
41+
- uses: actions/checkout@v4
4242
with:
4343
fetch-depth: 0
4444
- uses: DeterminateSystems/nix-installer-action@main
@@ -51,15 +51,60 @@ jobs:
5151
EditorConfig:
5252
runs-on: ubuntu-latest
5353
steps:
54-
- uses: actions/checkout@v3
54+
- uses: actions/checkout@v4
5555
with:
5656
fetch-depth: 0
5757
- uses: greut/eclint-action@v0
5858

59+
ValidateJsonSchema:
60+
runs-on: ubuntu-latest
61+
steps:
62+
- uses: actions/checkout@v4
63+
with:
64+
fetch-depth: 0
65+
- uses: DeterminateSystems/nix-installer-action@main
66+
with:
67+
determinate: true
68+
- uses: DeterminateSystems/flakehub-cache-action@main
69+
- name: Validate JSON Schema
70+
run: nix develop --command jv ./schema.json
71+
72+
BuildAndPublishJsonSchemaDocs:
73+
runs-on: ubuntu-latest
74+
environment:
75+
name: github-pages
76+
url: ${{ steps.publish.outputs.page_url }}
77+
permissions:
78+
contents: read
79+
pages: write
80+
id-token: write
81+
steps:
82+
- uses: actions/checkout@v4
83+
with:
84+
fetch-depth: 0
85+
- uses: DeterminateSystems/nix-installer-action@main
86+
with:
87+
determinate: true
88+
- uses: DeterminateSystems/flakehub-cache-action@main
89+
- name: Set up GitHub Pages
90+
uses: actions/configure-pages@v5
91+
- name: Generate JSON Schema docs
92+
id: generate
93+
run: |
94+
mkdir -p dist
95+
nix develop --command generate-schema-doc --config expand_buttons=true schema.json dist/index.html
96+
- name: Upload docs
97+
uses: actions/upload-pages-artifact@v3
98+
with:
99+
path: ./dist
100+
- name: Publish docs to GitHub Pages
101+
id: publish
102+
uses: actions/deploy-pages@v4
103+
59104
SynthesizeIntegration:
60105
runs-on: ubuntu-latest
61106
steps:
62-
- uses: actions/checkout@v3
107+
- uses: actions/checkout@v4
63108
with:
64109
fetch-depth: 0
65110
- uses: DeterminateSystems/nix-installer-action@main

‎.github/workflows/update.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ jobs:
99
runs-on: ubuntu-latest
1010
steps:
1111
- name: Checkout
12-
uses: actions/checkout@v3
12+
uses: actions/checkout@v4
1313
- name: Check flake
1414
uses: DeterminateSystems/flake-checker-action
1515
with:

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,6 @@
22
result*
33
synthesize/integration-test-cases/builds
44
synthesize/integration-test-cases/generated-synthesis
5+
6+
# Docs output
7+
/dist

‎flake.nix‎

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,19 +3,15 @@
33

44
inputs.nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
55

6-
outputs =
7-
{ self
8-
, nixpkgs
9-
, ...
10-
} @ inputs:
6+
outputs = inputs:
117
let
128
nameValuePair = name: value: { inherit name value; };
139
genAttrs = names: f: builtins.listToAttrs (map (n: nameValuePair n (f n)) names);
14-
allSystems = [ "x86_64-linux" "aarch64-linux" "i686-linux" "x86_64-darwin" ];
10+
allSystems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
1511

1612
forAllSystems = f: genAttrs allSystems (system: f {
1713
inherit system;
18-
pkgs = import nixpkgs { inherit system; };
14+
pkgs = import inputs.nixpkgs { inherit system; };
1915
});
2016
in
2117
{
@@ -30,6 +26,8 @@
3026
codespell
3127
nixpkgs-fmt
3228
rustfmt
29+
jsonschema # provides the jv tool
30+
json-schema-for-humans # provides the generate-schema-doc tool
3331
];
3432
});
3533

@@ -40,12 +38,12 @@
4038
pname = "bootspec";
4139
version = "unreleased";
4240

43-
src = self;
41+
src = inputs.self;
4442

4543
cargoLock.lockFile = ./Cargo.lock;
4644
};
4745
});
4846

49-
defaultPackage = forAllSystems ({ system, ... }: self.packages.${system}.package);
47+
defaultPackage = forAllSystems ({ system, ... }: inputs.self.packages.${system}.package);
5048
};
5149
}

‎schema.json‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
{
2+
"$id": "https://raw.githubusercontent.com/DeterminateSystems/bootspec/v1.0.0/schema.json",
3+
"$schema": "https://json-schema.org/draft/2020-12/schema",
4+
"title": "NixOS bootspec v1 schema",
5+
"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.",
6+
"type": "object",
7+
"required": ["org.nixos.bootspec.v1"],
8+
"properties": {
9+
"org.nixos.bootspec.v1": { "$ref": "#/$defs/Bootspec" },
10+
"org.nixos.specialisation.v1": {
11+
"type": "object",
12+
"patternProperties": {
13+
"^.*$": {
14+
"type": "object",
15+
"properties": {
16+
"org.nixos.bootspec.v1": { "$ref": "#/$defs/Bootspec" }
17+
},
18+
"required": ["org.nixos.bootspec.v1"],
19+
"additionalProperties": true
20+
}
21+
}
22+
}
23+
},
24+
"patternProperties": {
25+
"^.*$": {
26+
"$ref": "#/$defs/Bootspec",
27+
"description": "Testing"
28+
}
29+
},
30+
"$defs": {
31+
"Bootspec": {
32+
"type": "object",
33+
"required": ["init", "kernel", "kernelParams", "label", "system", "toplevel"],
34+
"properties": {
35+
"init": {
36+
"type": "string",
37+
"description": "Nix store path to the stage-2 init, executed by initrd (if present)."
38+
},
39+
"kernel": {
40+
"type": "string",
41+
"description": "Nix store path to the kernel image."
42+
},
43+
"kernelParams": {
44+
"type": "array",
45+
"items": {
46+
"type": "string"
47+
},
48+
"description": "Kernel command line options.",
49+
"examples": [
50+
[
51+
"amd_iommu=on",
52+
"amd_iommu=pt",
53+
"iommu=pt",
54+
"kvm.ignore_msrs=1",
55+
"kvm.report_ignored_msrs=0",
56+
"udev.log_priority=3",
57+
"systemd.unified_cgroup_hierarchy=1",
58+
"loglevel=4"
59+
]
60+
]
61+
},
62+
"label": {
63+
"type": "string",
64+
"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`.",
65+
"examples": ["NixOS 21.11.20210810.dirty (Linux 5.15.30)"]
66+
},
67+
"system": {
68+
"type": "string",
69+
"description": "Nix system type the bootspec is intended for.",
70+
"examples": ["x86_64-linux", "aarch64-linux"]
71+
},
72+
"toplevel": {
73+
"type": "string",
74+
"description": "Top-level Nix store path of the system closure."
75+
},
76+
"initrd": {
77+
"type": "string",
78+
"description": "Nix store path to the initrd."
79+
},
80+
"initrdSecrets": {
81+
"type": "string",
82+
"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."
83+
}
84+
}
85+
}
86+
}
87+
}

0 commit comments

Comments
 (0)