Add a JSON schema

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## Unreleased
+
+- Added a JSON schema that specifies the configuration format.
+
 ## 1.0.1
 
 - Fixed an issue where a dynamically allocated ID could collide with a

README.md

@@ -8,7 +8,7 @@ Declaratively bear (manage) Linux users and groups.
 - Update user (password, description (gecos), home directory,
   shell) and group (members) information.
 - Prohibit UID/GID re-use.
-- Simple JSON config format.
+- Simple JSON config format with a [JSON Schema](./userborn.schema.json).
 - Create per-user groups if no explicit primary group is provided.
 - Warn about insecure password hashing schemes.
 - Manage `/etc/subuid` and `/etc/subgid` for rootless containers.
@@ -91,6 +91,12 @@ and later added to the Userborn config. For example:
 You can configure Userborn during runtime via the provided config file and via
 environment variables.
 
+### Config
+
+The config file is specified in a [provided JSON
+schema](./userborn.schema.json) which you can use to see available options and
+to validate your config.
+
 ### Environment Variables
 
 - `USERBORN_MUTABLE_USERS`: Set this to the string `true` if you want to enable

flake.nix

@@ -43,23 +43,30 @@
         system:
         let
           pkgs = nixpkgs.legacyPackages.${system};
-          overlayedPkgs = pkgs.extend (_final: _prev: { inherit (self.packages.${system}) userborn; });
+          userborn = self.packages.${system}.userborn;
+          overlayedPkgs = pkgs.extend (_final: _prev: { inherit userborn; });
         in
         {
-          clippy = self.packages.${system}.userborn.overrideAttrs (
+          clippy = userborn.overrideAttrs (
             _: previousAttrs: {
               pname = previousAttrs.pname + "-clippy";
               nativeCheckInputs = (previousAttrs.nativeCheckInputs or [ ]) ++ [ pkgs.clippy ];
               checkPhase = "cargo clippy";
             }
           );
-          rustfmt = self.packages.${system}.userborn.overrideAttrs (
+          rustfmt = userborn.overrideAttrs (
             _: previousAttrs: {
               pname = previousAttrs.pname + "-rustfmt";
               nativeCheckInputs = (previousAttrs.nativeCheckInputs or [ ]) ++ [ pkgs.rustfmt ];
               checkPhase = "cargo fmt --check";
             }
           );
+          # Check whether the vendored schema is up-to-date with the Rust
+          # sources.
+          vendored-schema = pkgs.runCommand "vendored-schema" { } ''
+            ${pkgs.diffutils}/bin/diff --color ${./userborn.schema.json} ${userborn.dev}/userborn.schema.json
+            touch $out
+          '';
           pre-commit = inputs.pre-commit.lib.${system}.run {
             src = ./.;
             hooks = {

nix/packages/userborn.nix

@@ -2,6 +2,7 @@
   lib,
   rustPlatform,
   libxcrypt,
+  withJsonschema ? true,
 }:
 
 let
@@ -17,6 +18,13 @@ rustPlatform.buildRustPackage {
     ".lock"
   ];
 
+  outputs = [
+    "out"
+  ]
+  ++ lib.optionals withJsonschema [
+    "dev"
+  ];
+
   cargoLock = {
     lockFile = ../../rust/userborn/Cargo.lock;
   };
@@ -29,6 +37,14 @@ rustPlatform.buildRustPackage {
     libxcrypt
   ];
 
+  buildFeatures = lib.optionals withJsonschema [ "jsonschema" ];
+
+  postInstall = lib.optionalString withJsonschema ''
+    mkdir -p $dev
+    $out/bin/jsonschema > $dev/userborn.schema.json
+    rm $out/bin/jsonschema
+  '';
+
   stripAllList = [ "bin" ];
 
   meta = with lib; {

rust/userborn/Cargo.toml

@@ -3,13 +3,18 @@ name = "userborn"
 version = "1.0.1"
 edition = "2024"
 
+[[bin]]
+name = "jsonschema"
+required-features = ["jsonschema"]
+
 [dependencies]
 anyhow = "1.0.100"
 log = "0.4.29"
 serde = { version = "1.0.228", features = [ "derive" ] }
 serde_json = "1.0.149"
 env_logger = { version = "0.11.8", default-features = false }
 xcrypt = "0.3.2"
+schemars = { version = "1.2.2", features = [ "preserve_order" ], optional = true }
 
 [dev-dependencies]
 indoc = "2.0.7"
@@ -21,6 +26,9 @@ panic = "abort"
 lto = true
 strip = true
 
+[features]
+jsonschema = ["dep:schemars"]
+
 [lints.rust]
 unsafe_code = "forbid"
 
@@ -32,3 +40,4 @@ expect_used = { level = "deny", priority = 1 }
 needless_raw_string_hashes = { level = "allow", priority = 1 }
 struct_field_names = { level = "allow", priority = 1 }
 module_name_repetitions = { level = "allow", priority = 1 }
+missing_errors_doc = { level = "allow", priority = 1 }

rust/userborn/src/bin/jsonschema.rs

@@ -0,0 +1,9 @@
+use userborn::Config;
+
+fn main() {
+    let schema = schemars::schema_for!(Config);
+    println!(
+        "{}",
+        serde_json::to_string_pretty(&schema).expect("Failed to generate jsonschema.")
+    );
+}