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

• 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.