Module-schema

A Nix library to generate JSON Schemas for modules as defined in the Nixpkgs manual.

Motivation

NixOS modules are a great way to configure software, however, they require interacting with Nix. This puts them out of reach of many non-technical users. Their options do declare types, so enough information is available for an alternative interface, such as a web form, to show the available options and to validate a configuration before Nix evaluates it.

This library generates a schema with that information. It opts for JSON Schema as defined in draft 2020-12: JSON is easy to process in many programming languages, and the validation vocabulary covers most of the constraints encoded in Nixpkgs' lib.types. The intent is for JSON data that passes validation against a generated schema to lead to a Nix value (using builtins.fromJSON) that passes all the checks of the option types involved. The manual elaborates on the motivation.

Usage

lib.module-schema.optionsToSchema takes an attrset of NixOS module system options and returns a Nix representation of a JSON Schema, ready for builtins.toJSON.

With npins, or any other way of getting the sources:

let
  module-schema = import sources.module-schema { };
in
builtins.toJSON (
  module-schema.lib.module-schema.optionsToSchema (pkgs.nixos { }).options.services.peertube
)

default.nix is the source of truth and takes system, sources, lib and pkgs as optional arguments, so a package set can be supplied instead of the pinned one.

As a flake input:

{
  inputs.module-schema.url = "git+https://git.fediversity.eu/fediversity/module-schema";

  outputs =
    { module-schema, ... }:
    {
      # ...
    };
}

The flake declares no inputs of its own: the pin in npins/sources.json is the only one, so inputs.nixpkgs.follows has no effect. Call default.nix with your own sources to override it.

Run unit tests with nix-shell --run 'nix-unit lib/tests'. To also build the docs use nix-build --no-out-link -A checks or nix flake check -- which show sub-tests only on failure.

Format all files by running nix-shell --run treefmt.

Documentation

The manual and reference documentation are available here, deployed from the main branch. The manual covers the motivation, usage, the types the library can represent, and related projects.

Note on the internal convention

Internal namespaces are a convention inherited from Haskell. Instead of hiding implementation details they are accessible for when the public API simply doesn't suffice. The contract is that anything in an internal namespace may change in any way, at any time. The burden of keeping implementation sites functional is on the user of such interfaces.