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

Add JSON schema for .ort.yml configuration #4639

Merged

Conversation

MarcelBochtler
Copy link
Member

@MarcelBochtler MarcelBochtler commented Oct 29, 2021

A JSON schema 1 is a description of a JSON document, which can also be
used for YAML files. This schema can be used to enable auto-completion
in multiple editors for the .ort.yml file 2. E.g. IntelliJ IDEA has build-in support
for it 3:
Screenshot 2021-10-29 at 11 21 44

As a next step, the URL to this schema can be contributed to https://github.com/schemastore/schemastore/ and many editors will then have autocompletion for .ort.yml out of the box.

It would be nice to autogenerate this file, however I didn't find a convenient way to do this.
Adding the test coverage to avoid regressions in the schema should be good enough for now.

Missing as of now is the documentation from the model classes. It would be nice to also get this documentation during auto completion.

I opted to use the JSON format instead of a YAML format, to ensure better compatibility. I was e.g. not able to use a YAML schema with VS Code.

@MarcelBochtler MarcelBochtler requested a review from a team as a code owner October 29, 2021 11:30
@MarcelBochtler MarcelBochtler changed the title Ort yml json schema Add JSON schema for .ort.yml configuration Oct 29, 2021
@@ -0,0 +1,433 @@
{
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there any benefit in putting this file in the source tree? Otherwise I would suggest to put it somewhere, maybe the "integrations" folder, and test it similar to how the examples are tested.

model/build.gradle.kts Outdated Show resolved Hide resolved
@sschuberth
Copy link
Member

sschuberth commented Oct 29, 2021

It would be nice to autogenerate this file, however I didn't find a convenient way to do this.

Would you mind listing the tool you looked at? For example, did you try https://github.com/FasterXML/jackson-module-jsonSchema?

Edit: As a note to myself, if we'd be using kotlinx.serialization, we could probably use https://github.com/Ricky12Awesome/json-schema-serialization.

@MarcelBochtler
Copy link
Member Author

MarcelBochtler commented Oct 29, 2021

It would be nice to autogenerate this file, however I didn't find a convenient way to do this.

Would you mind listing the tool you looked at? For example, did you try https://github.com/FasterXML/jackson-module-jsonSchema?

I tried https://github.com/mbknor/mbknor-jackson-jsonSchema.
This has some nice options to manipulate the generated schema, which might be handy to have. However, it has issues with the required option. It uses nullable types to find the required parameters. As in ORT's models the fields are not nullable they are all generated as required.
I didn't find a way to work around this issue. (manually setting the parameters as not required does also not work)

I also tried your linked https://github.com/FasterXML/jackson-module-jsonSchema.
Unfortunately the generate schema was not valid, or at least it was not usable within VS Code:

Problems loading reference 'urn:jsonschema/%3Aorg%3Aossreviewtoolkit%3Autils%3Aspdx%3Amodel%3ALicenseChoice': Unable to load schema from 'urn:jsonschema/%3Aorg%3Aossreviewtoolkit%3Autils%3Aspdx%3Amodel%3ALicenseChoice': No content.

And the required option is also not controllable and does not generate the correct scheme for the RepositoryConfiguration.

@@ -60,6 +60,10 @@ Files: clients/github-graphql/src/main/assets/*
Copyright: 2021 Bosch.IO GmbH <osm@bosch.com>
License: Apache-2.0

Files: integrations/schemas/*
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Commit message nits:

A JSON schema [1] is a description of a JSON document, which can also be
used for YAML files. This schema can be used to enable auto-completion
in multiple editors for the .ort.yml file [2]. E.g. IntelliJ IDEA has
build-in support for it [3].

[1]: https://json-schema.org
[2]: https://www.schemastore.org/json
[3]: https://www.jetbrains.com/help/idea/json.html#ws_json_schema_add_custom

Signed-off-by: Marcel Bochtler <marcel.bochtler@bosch.io>
Signed-off-by: Marcel Bochtler <marcel.bochtler@bosch.io>
@MarcelBochtler MarcelBochtler merged commit 845b9d6 into oss-review-toolkit:master Nov 1, 2021
@MarcelBochtler MarcelBochtler deleted the ort-yml-json-schema branch November 1, 2021 17:26
@sschuberth sschuberth added the release notes Changes that should be mentioned in release notes label Nov 3, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
release notes Changes that should be mentioned in release notes
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants