[Feature Request] Add JSON schema to help configure 'GitVersion.yml'

[BinToss]

Detailed Description

GitVersion only has a JSON schema for the output JSON, but it lacks one for the input YAML/JSON config.

Context

I've found that going back and forth between the documentation and the config file I'm editing takes up more time than it could if my editor was able to detect a schema and use that to suggest properties and values. It wouldn't be perfect, but nothing is.

[asbjornu]

Sounds like a great idea! Is this something we could make editors such as Visual Studio Code use for code completion and such as well?

[BinToss]

So long as the user has the RedHat YAML language server installed and enabled, as well as the appropriate IntelliSense settings, I believe so. Visual Studio IDE's IntelliSense should work the same depending on the IDE versions' support for YAML and JSON.

…

On Mon, Oct 11, 2021, 7:05 AM Asbjørn Ulsberg ***@***.***> wrote: Sounds like a great idea! Is this something we could make editors such as Visual Studio Code use for code completion and such as well? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#2874 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABXILNV3TWWGYIJCD4KPAMDUGLVIXANCNFSM5FV4FI3Q> .

[BinToss]

The existing GitVersion.json schema for the GitVersion *output* works for suggestions, I recall now.

…

On Mon, Oct 11, 2021, 7:05 AM Asbjørn Ulsberg ***@***.***> wrote: Sounds like a great idea! Is this something we could make editors such as Visual Studio Code use for code completion and such as well? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#2874 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABXILNV3TWWGYIJCD4KPAMDUGLVIXANCNFSM5FV4FI3Q> .

[asbjornu]

Where is this existing GitVersion.json schema located?

[BinToss]

https://json.schemastore.org/gitversion.json
I'm not sure where it came from or who made it.

[arturcic]

@BinToss I think the schema is versioned here https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/gitversion.json. A PR there should add the missing parts

[BinToss]

I can't recommend using one schema file for...two schemas. Ham-fisting a mix of incompatible values into a schema would confuse code editors that support JSON Schema matching. GitVersion expects 'gitversion.yml' and 'gitversion.json' to have different contents, but a JSON schema expects the yml and json extensions to be interchangeable. This means that one or the other must have its filename changed to prevent collisions. Hopefully, this change will be as simple as "Replace 'gitversion.yml' with 'gitversion.cfg.yml' in all files" so we can have non-colliding schemas.

[asbjornu]

I have no idea how this works, but your suggested solution sounds good @BinToss. I suppose that's up to @SchemaStore, though?

[stale]

This issue has been automatically marked as stale because it has not had recent activity. After 30 days from now, it will be closed if no further activity occurs. Thank you for your contributions.

[BinToss]

I recently learned that one can specify a JSON schema via a "$schema" property in the JSON/YAML file. This property allows both URLs and local file paths. The schema filename can be different than the current file's name.

This means that the filenames of GitVersion.yml and GitVersion.json do not need to be changed.

Example

https://developer.microsoft.com/json-schemas/sp/site-design-script-actions.schema.json

Documentation

https://json-schema.org/draft-04/json-schema-core.html#rfc.section.6

---

Consequently, we now have three more solutions for GitVersion.json and GitVersion.yml:

• host both files' schemas in a GitVersion-owned repo or branch and access them remotely.
• package both schemas with GitVersion, copy them to be alongside their respective json/yml, and write the relative path to those files.
• Generate the schemas during runtime based on what's available in the currently executing GitVersion assembly.

GitVersion CLI is already capable of generating and configuring a config file. Depending on how that's implemented, also generating a schema should be relatively easy.

[asbjornu]

host both files' schemas in a GitVersion-owned repo or branch and access them remotely.

I like this option and think we should expose them through the website on gitversion.net. A PR adding GitVersion.json and GitVersion.yml to the website would be appreciated.