# ADR-0008: JSON Schema for YAML config is generated from plugin metadata, not hand-written

| Field         | Value       |
|---------------|-------------|
| Kind          | ADR         |
| Status        | Accepted    |
| Decided       | historical  |
| Deciders      | Antoine Berchet |
| Supersedes    | —           |
| Superseded by | —           |

## Context

CIF's YAML configuration surface is large and grows with every new plugin: each plugin
module declares its own `input_arguments` (see ADR-0006). Hand-maintaining a separate
JSON Schema for editor validation/autocompletion would inevitably drift from what
plugins actually accept — nobody can keep 16 plugin categories, each with many plugins,
in sync by hand across two independent sources of truth.

## Decision

The JSON Schema (`pycif_config.schema.json`, published at
`http://community-inversion.eu/pycif_config.schema.json`) is generated programmatically
from the same `Plugin.plugin_types` / `plugin_subtypes` registry and each plugin's
declared `input_arguments`
([`docs/source/json_schema/make_schema.py`](https://gitlab.in2p3.fr/satinv/cif/-/blob/devel/docs/source/json_schema/make_schema.py)
+ `parse_plugins.py`), and rebuilt on every Sphinx docs build (`conf.py`'s
`build_schema()` hook calls `make_schema()` and writes the result into the docs output),
rather than hand-written or committed as a static file.

## Consequences

- The schema can never drift from the code: any plugin's `input_arguments` change is
  reflected in the schema on the next docs build.
- The schema cannot usefully be edited by hand — it's a generated build artifact that
  gets overwritten every build. A fix belongs in the plugin's `input_arguments`, not in
  `pycif_config.schema.json` directly.
- `build_schema()` has no error handling around `make_schema()`: if schema generation
  raises, the docs build fails outright rather than silently publishing a stale or
  partial schema. This is a safety net, not a risk, but it does mean a bug in one
  plugin's `input_arguments` can block the whole docs build, not just that plugin's page.
- Only plugin categories listed in `ROOT_LEVEL_PLUGIN` (`make_schema.py`) get top-level
  schema entries; adding a wholly new plugin category needs an explicit addition there
  or its plugins won't surface in autocompletion.
- This is documented for end users at `docs/source/usertutos/autocompletion.rst` (VS
  Code YAML autocompletion setup) — that page's usefulness depends on this generation
  step staying wired into the docs build.