add schema declaration to the manifest file

[baronfel]

trafficstars

This change allows editors to highlight data errors. While this won't entirely prevent bad data, it opens the door to using the schema in more automated fashions (for example a unit test that validates the document according to the schema).

Here's what the experience looks like for a subset of invalid field data in VS Code:

and in VS:

The tooltips are powered by the schema and offer tips for fixing the problem:

[rbhanda]

@leecow will this be a breaking change somehow to the release-index.json?

[baronfel]

I checked the .NET library that parses this file and it would not impact that library because it specifically pulls the releases-index property of the json document and then deserializes that array.

This library is used in the SDK, omnisharp, arcade, and probably others based on the NuGet listing, so I would hope that since it parses this correctly there would not be too much churn.

[leecow]

My primary question is how is the schema maintained updated in the event of an update in either the json structure (e.g. adding a property) or updating valid values (which we will likely be doing for support phase)?

[baronfel]

The schema itself is currently housed here, and that repo has typically had relatively quick turnaround from my experience - usually within a few hours of PR submission assuming checks green eup.

There's an alternative here to including the schema annotation in the file - some IDEs can use an external setting to map a schema to a file, VSCode is great about this. I haven't yet found a similar mechanism for VS.

If agility in the schema itself is a requirement, the schema file could live in this repo, and schemastore could just be a pointer to the file in this repo. That's also a very quick change to make.

If breaking changes to the schema are made, then we'd need to version it (this is conventionally done by appending version numbers) and probably have the unversioned schema file alias the latest version. But I'd expect that most changes would be additive (a new property or a new enum case) in which case it's a fairly simple matter of adding a definition for the property/enum case.

[leecow]

This change needs to happen in the tooling which generates and maintains the file. I've submitted a PR to schemastore to update the releases-index schema. Once that's complete, I'll update the tooling.