Adding JSON schema to schemastore.org

Coding
1

I’d like to add the Caddy JSON schema to schemastore.org (or other hosted schema repo) but wanted to open a discussion here first to figure out approach since this topic has been brought up a few times before (example 1, example 2, example 3). My argument for making this official is as follows:

Why?

Generating the caddy schema with caddy-json-schema is a trivial operation to automate, but involves compiling a custom version of caddy with the plugin installed just to get access to a metadata document for a public API. Since the schema is well documented, there’s no reason to not fill the last 1% by bringing IDE autocomplete support.

What about plugins?

As Matt has stated:

I would counter that the vanilla, publically distributed (installed from a package manager) version of Caddy is the same for everyone. If a user builds caddy with extra plugins it would make sense for them to need to take extra steps to get a schema customized for their specific use. For everyone else who installs Caddy in its standard configuration, putting the schema behind a plugin that has to be included in the build or custom-downloaded from the website raises the barrier for those wanting to tinker with the JSON config.

Solutions

There’s a few approaches that could be taken here:

  • Open a pull request to SchemaStore/schemastore with a hand-edited schema based on what caddy-json-schema generates. This is the lowest effort, and most IDE’s will pick it up automatically. If Caddy’s standard JSON config structure changes frequently, pull requests will need to be made to update it.
  • Host the JSON schema on Caddy’s GitHub. Since schema sources can be any URL and because schema generation can be automated, schema maintenence can be done regularly and automatically.
  • Any other approaches… I don’t know if there’s another place to host JSON schemas or if there’s some sort of Go-thing that can ease automation/hosting of Caddy’s schemas.

Thanks in advance to all for your suggestions or discussion around this! I think having the vanilla schema published would really help people (myself included) when confronted with Caddy’s JSON config structure and any way to lower that barrier further would be awesome to have.

2

Hi @noelforte – thanks for opening this discussion.

Does JSON that does not match the schema produce errors in any implementations/IDEs? If so, I don’t know if it would be a good idea, since any use of third-party Caddy modules would cause errors in their config documents.

Ideally, the JSON schema used for validation would be the correct one.

What I could see working though, but it might require some work, is:

  • Generate a single JSON schema with all registered modules (i.e. our website’s JSON docs, but fully expanded into a single document).
  • Somehow indicate which parts of the config require third-party modules, and where/how to get them
  • Distribute that, and editors can implement support for showing those info messages (not errors – mayyyybe warnings), particularly if their local Caddy installation doesn’t have those modules.
1 Like