JSON Schema File

[DanzigerGeist]

Description

Would it be possible to host a JSON schema for the cz.json configuration file in order to enable the syntax checks?

For example, in Deno projects we add the following field to deno.json file:

"$schema": "https://deno.land/x/deno/cli/schemas/config-file.v1.json"

This could be extremely useful for configuration checks and validation.

Possible Solution

No response

Additional context

No response

Related issues

No response

[Lee-W]

I'm not sure I'm a fan of adding this check 🤔 It does not look like a standard thing. (or maybe I'm wrong) Would love to hear what @woile and @noirbizarre think

[woile]

I think it's a good idea. A JSON Schema works for other formats, including toml. We would have to create the schema based on the default setting class and just host it in our website. Then you just reference it as a comment in toml or with $schema key in JSON. Tools like pydantic generate the json schema right away from a base model for example. In our case, we would have to write some inference code, but it should be possible.

It's a very interesting issue if someone wants to pick it up.

[yjaw]

Hi, I’d be happy to take this one. I’ve identified two approaches to implementing the schema:

1. Using DEFAULT_SETTINGS as the Source of Truth: Pydantic references our existing settings, which will result in minimal breaking changes.
2. Using Pydantic as the Source of Truth: Pydantic generates a dictionary for the DEFAULT_SETTINGS, which will be more suitable for long-term maintenance.

I personally prefer Option 1 because it doesn’t affect the current codebase and is essentially a plug-in for users who use JSON format. Does this align with your vision for the project, or do you have a different implementation in mind?

[woile]

In principle, I think the initial goal should be scoped to releasing our schema to https://www.schemastore.org/

This way, IDE's can automatically pick it up, or teams can reference in the file using:

#:schema https://json.schemastore.org
[tool.commitizen]

How?

This is open to debate.
I don't think we should add anything extra to commitizen, and we could have a new dev dependency group with pydantic to generate the schema. This code, could be a script under scripts/gen_json_schema.py, and run in the CI.

Future work
How to take into account plugins? I'm not sure yet, but I think we can think of that in the future, there has to be more work done on the settings, like how to allow plugins to extend the settings, but there's nothing clear for this yet.