Related projects

Turning module options into something a non-Nix program can consume is not a new idea. This page sketches what else exists, what each effort is for, and where the approaches coincide.

Clan-core's lib/jsonschema

Clan-core is the closest relative, and the most developed. Its authors have written up the design twice: a JSON Schema converter for NixOS modules and a follow-up.

Their goal. Module options as the single source of truth for a polyglot product stack. The schema is as much a representation made for their Python and TypeScript clients as a validation artifact. They are explicit that they control both ends, which lets them target a chosen subset of JSON Schema rather than the whole dialect.

Their second generation. One schema per module turned out to be the wrong model, because the module system is a transformation: defaults are filled in, definitions are merged, values are coerced. What a user writes and what the module produces are different shapes. They now emit two schemas -- a permissive write (input) schema and a total read (output) schema -- aiming for read to be a subtype of write.

Where we coincide. Both walk evaluated options and dispatch on type.name, both target draft 2020-12, and both drop visible = false options.

Where we differ, at the level of goals. Module-schema is a standalone library whose output is a validation contract for a user-facing interface such as a web form, not an intermediate representation. It therefore has no type-name prefixing and no per-language naming contract. It emits one schema rather than an input/output pair, and deliberately over-approximates required, so that anything validating against the schema is deployable. And where Clan flattens alternatives into oneOf, Module-schema first tries to merge them into a single schema: either int str becomes type = [ "integer" "string" ], with the interval arithmetic in lib.interval backing the numeric cases.

Inverse direction

Json-schema-nix goes the other way, generating module options from a JSON Schema.

Complement, not competitor

Nix-module-form consumes a JSON Schema and renders a form from it. It is the downstream half of the same pipeline, not an alternative to this library.