feat: JSON Schema for commitizen configuration (issue #1565)

.github/workflows/pythonpackage.yml

@@ -23,6 +23,8 @@ jobs:
             relevant:
               - "commitizen/**"
               - "tests/**"
+              - "schemas/**"
+              - "scripts/**"
               - ".github/workflows/**"
   python-check:
     needs: detect_changes

pyproject.toml

@@ -108,12 +108,14 @@ test = [
     "pytest-xdist>=3.1.0",
     "pytest-gitconfig>=0.9.0",
     "pre-commit>=4.5.1",
+    "jsonschema>=4.26.0",
 ]
 
 linters = [
     "ruff>=0.11.5",
     "mypy>=1.16.0",
     "types-deprecated>=1.2.9.2",
+    "types-jsonschema>=4.26.0.20261006",
     "types-python-dateutil>=2.8.19.13",
     "types-PyYAML>=5.4.3",
     "types-termcolor>=0.1.1",

schemas/README.md

@@ -0,0 +1,10 @@
+# JSON Schemas for Commitizen configuration
+
+This directory contains two related schemas because the configuration shapes differ:
+
+- `commitizen-config.schema.json` describes the settings object itself. Use it for the `[tool.commitizen]` table in `pyproject.toml` with a `#:schema` comment.
+- `commitizen-wrapper.schema.json` describes a complete `.cz.json` or `.cz.yaml` file, where the settings are nested under the top-level `commitizen` key. The wrapper schema uses the SchemaStore identifier `https://json.schemastore.org/commitizen.json`.
+
+The generator derives settings properties and defaults from Commitizen's configuration types, while its question schema follows the prompt options accepted by the runtime. Run `python scripts/gen_json_schema.py` to regenerate both files, or `python scripts/gen_json_schema.py --check` to verify that both committed schemas are current.
+
+See issue #1565 for the original design discussion.