metadata.json

metadata.json is the machine-readable reference the website consumes. nix build .#docs-metadata writes it; nix build .#docs writes it next to the rendered Markdown.

Synopsis

{
  "revision": "string",
  "contracts": [Contract],
  "modules": [Module],
  "kernel": { "providers": [Option], "secretRef": [Option] }
}

revision is the flake revision, or unknown outside a Git checkout.

Contract

{
  "name": "http",
  "description": "HTTP exposure. ...",
  "implementers": ["traefik"],
  "options": [Option]
}

name is the contract key under providers and needs. implementers lists the imported modules whose implements list contains this contract. options are the need options a consumer may set or read.

Module

{
  "name": "traefik",
  "description": "Traefik ingress controller. ...",
  "implements": ["http"],
  "needs": ["dns"],
  "external": false,
  "options": [Option]
}

name is the type key under apps. options are the instance options, without the generic dnsLabel, namespace, and needs keys. external is true for a provider with no apps instance. The implements field lists the contracts the module provides.

Option

{
  "name": "host",
  "type": "null or string",
  "description": "Fully qualified host. Defaults to the consumer DNS label under the bound zone.",
  "readOnly": false,
  "default": { "_type": "literalExpression", "text": "null" }
}

name is the option path relative to its owner. For a freeform contract, <name> stands for the attribute a consumer chooses, as in volume.<name>.size. default and example are present only when the option declares one, and carry the same shape as the NixOS options JSON.

Kernel

kernel.providers holds one entry per contract key under providers. kernel.secretRef holds the three fields of a secretRef: name, key, and namespace.