Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Provide JSON schema for deny.toml file for better IDE experience #632

Open
Veetaha opened this issue Mar 15, 2024 · 6 comments
Open

Provide JSON schema for deny.toml file for better IDE experience #632

Veetaha opened this issue Mar 15, 2024 · 6 comments
Labels
enhancement New feature or request

Comments

@Veetaha
Copy link
Contributor

Veetaha commented Mar 15, 2024

It's possible to associate a JSON schema with a TOML file to make a VSCode extension such as "Even Better TOML" (taplo) provide completions, documentation, type hints and validation in the IDE. Details on the config are here.

I propose cargo-deny to provide a JSON schema definition file that completely describes the deny.toml file format.

Discoverability

I propose to submit the schema to the JSON Schema Store such that TOML IDE plugins can discover the schema without any additional configs.

Alternatively people could set the file schema with #:schema {schema-uri-here} comment at the top of the file, but it would be better if that was automatic via the JSON Schema Store.

Implementation notes

I'm not sure how exactly this should be implemented, but I know of schemars crate that can generate a JSON schema automatically from Rust code.

@Veetaha Veetaha added the enhancement New feature or request label Mar 15, 2024
@Jake-Shadle
Copy link
Member

Seems reasonable.

@Veetaha
Copy link
Contributor Author

Veetaha commented Mar 17, 2024

I'd like to claim this issue, if no one else is working on it

@Jake-Shadle
Copy link
Member

Sure, go for it. Note you'll not be able to use schemars, both because serde is no longer used for the configuration, and it also has really outdated dependencies that I'd rather not burden cargo-deny with eg. GREsau/schemars#269

@Veetaha
Copy link
Contributor Author

Veetaha commented Mar 17, 2024

I see, that's a bummer. Although schemars allows using custom overrides #[schemars(...)] in case serde isn't used, but the fact that it is unmaintained is reasonable.

In theory we could write the JSON schema manually. It is human-readable and its format also has its own schema so IDE's are helpful with writing that file. I'm thinking of using YAML for that definition though and converting that YAML to JSON. This is because JSON doesn't play well with multiline strings, which appear in documentation, and also has no support comments.

On the other hand with the manual approach there is a lot of flexibility and it's possible to define complex validations.

@Jake-Shadle
Copy link
Member

I haven't thought about implementation much yet since you only opened this recently, but ideally it would be something along these lines:

  1. Ideally has 0 additional dependencies.
  2. Validated in CI
  3. Tight integration with the book documentation. Right now there is some duplication between Rust comments and the book, and I wouldn't want yet another place with duplicated descriptions of fields. Ideally there would be a single source of truth that could generate the other pieces. If that's hard to do without adding dependencies, it could maybe be done by moving that code outside of cargo deny itself into a separate binary, that then generates rust/markdown/json from something (either those, or something else entirely) so that only one place needs to be edited (well, at least for the stuff like descriptions or the like, obviously since we aren't using serde changing the actual fields would need to change the deserialization code).

@Veetaha
Copy link
Contributor Author

Veetaha commented Mar 17, 2024

Makes sense, I'll try to find a way to make the JSON schema the source of the truth for the mdbook as well

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants