Config file schema directive is incompatible with TOML linters and language servers available

[uchoa]

Description

Considering Taplo and Tombi as good examples of schema validation implementation, both define the schema to be used with a TOML file with the following format:

#:schema https://jj-vcs.github.io/jj/latest/config-schema.json

while the config file template used by jj is:

"$schema" = "https://jj-vcs.github.io/jj/latest/config-schema.json"

Steps to Reproduce the Problem

1. jj config set [--user/--repo] KEY VALUE
2. Open the corresponding config file for editing

Expected Behavior

My editor using a TOML linter/language server should be able to validate the configuration against the referenced schema.

Actual Behavior

The linter/language server doesn't validate the file due to the unexpected format used to reference the schema.

Specifications

• Platform: Linux + Neovim + [Taplo | Tombi]
• Version: jj 0.30.0

[ilyagr]

Taplo is supposed to support a $schema top-level key, as per https://taplo.tamasfe.dev/configuration/using-schemas.html. I know this worked for me in VS Code, does it not work in Neovim? Or did it stop working in VS Code as well?

Does Tombi not support that? Would they perhaps consider implementing it?

To me, $schema top-level key seems pretty sensible, since that's what JSON uses and we're using JSON schemas.

Update: I also filed tombi-toml/tombi#647, following my best guess as to what's going on.

[uchoa]

I can't talk about VSCode, as I haven't used it for years now, but in Neovim Taplo gives me a warning stating that I don't have a schema if I don't use the format I mentioned in the issue description. BTW, the Taplo URL you cited in your comment is the one I had found when I looked for it: what they use in the example in that page is a schema directive in the form of #:schema ./foo-schema.json.

[ilyagr]

Tombi's author says they don't intend to support "$schema" key until some community discussion about TOML schemas settles.

On our side, the easy thing to do is to update our docs accordingly to mention the #:schema format.

I am curious whether any editor setup supports "$schema" and not #:schema, but I'm not currently aware of any. In my testing, all the options except for IntelliJ use Taplo or Tombi, and IntelliJ seems to actually support neither "$schema" nor #:schema (which is another reason to update the docs).

The slightly harder thing would be to change the code that inserts the schema when creating a new config file. I tried the simplest thing possible, and it unfortunately is a mess; toml_edit does support comments in theory, but they get lost and misplaced, and there's no explicit way to manipulate them.

Another option would be to simply search the file for #:schema at the beginning of a line before outputting it, and prepending #:schema https://jj-vcs.github.io/jj/latest/config-schema.json if no such line is found.

Once we're settled on an approach, the rest of the work would be mostly updating tests.

BTW, the Taplo URL you cited in your comment is the one I had found when I looked for it: what they use in the example in that page is a schema directive in the form of #:schema ./foo-schema.json.

No, I linked to a slightly different page. Quoting https://taplo.tamasfe.dev/configuration/using-schemas.html's item 3, taplo is supposed to support specifying schemas "as an URL under the $schema key in the root of the document", which is what we're now doing. So, I'm not sure what's happening with Neovim/Taplo, but I haven't tested it either.

[ilyagr]

I will also try to put our schema into the schema store that Tombi and Taplo use, SchemaStore/schemastore#4830. (Update: It's merged now).

Hopefully, this will help some people, though it would only add to the confusion if Tombi uses the version from the schemastore while a different version of the schema is specified in "$schema".

[ilyagr]

This should hopefully have been fixed in #7383 for the next release.