Feature Request: JSON Schema for edge.json

[sbonami]

To help our team build better software and identify issues earlier in our development process, we've been toying with the idea of introducing a JSON Schema to our edge.json files. For the unfamiliar, JSON Schemas have the added benefit of being used for validation automatically within IDEs, which allows developers to shift left in their development process and identify issues sooner.

I know there's already support in this library for validation, so this is either in addition to, or a potential replacement of, that functionality. While I'm neither for or against this, the library could perhaps use a schema validator library during the validation phase and eliminate any duplicative logic.

I would be willing to start this work and contribute to the library, however, I wanted to get insight from users and maintainers first. I would need a pointer to any data model references that I should use if we opt to move forward. I poked around and found this to be generally possible for the edge.json files but I've yet to reach a hypothesis on how to do this for the directory-style config files given the root is an array rather than an object (where the $schema designation goes). I'd look to see if we can set a schema without introducing a breaking change to those files.

[ssvaidyanathan]

@sbonami - its a great idea. I always recommend using the folder structure instead of the single edge.json because that single file can be really long and difficult to read and can often be error prone

So have you looked at that option? Do you think we should work on creating a JSON schema ref for the edge.json and also for the individual folders?

[sbonami]

I did a little more research and found this to be somewhat controversial: https://github.com/json-schema-org/json-schema-spec/issues/828. Essentially, authors contend that specifying any key as having special meaning (e.g. { "$schema": "<url to schema>" } violates the open nature of JSON at best, and at worst conflicts with other sub-standards of JSON. The only suggestion that's part of the spec mentions an HTTP header, but that doesn't apply to this use-case as merely a configuration file. Any documented cases of a specific key are merely common conventions and not driven by the specification.

I think in the case of this library, though, we're in the clear and can use the $schema convention. This file is an internal configuration file and it's only utilized by the library itself, so we can safely use any key we want (like $schema) and not fall victim to parsing errors. This is easy to do in the edge.json file.

The good news is that we can have schemas and sub-schemas, so it's not hard for the edge.json schema to reference sub-schemas that align with each of the individual files.

However... the issue is with the json files within the folder structure. Those are built with an array at the root, which isn't keyed in JSON and can't reference a schema. Additionally, JSON doesn't support inline comments so there isn't an alternate // $schema: <url to schema> trick.

I think then that we are left with three options:

1. issue a breaking change that rewrites the individual config files using an object at the root so that the $schema can be used
2. issue a backwards-compatible change that can perform option 1 while still respecting the root array without the $schema
3. add guidance to the README (like VSCode docs) suggesting use of the schema through project/workspace specifications

[ssvaidyanathan]

@sbonami - Thanks for the details

Regarding the options - not sure we can introduce a breaking change. MOST of the plugin users use folder structure and they will all have impacts with this.

do you have suggestion on your 2nd option? How can we achieve that?

Regarding 3rd option, how do we support developers using other IDEs or tools to generate these files?

[ssvaidyanathan]

How about we add a new Maven goal that validates the schema of the edge.json and the individual files to make sure its following the defined schema? and have that as an option for someone to run? When I say schema, I am just verifying the structure of the json not really running against a JSON schema definition

[sbonami]

I think that's a great addition! Tbh I wouldn't know where to start as I've not contributed to a Maven project before, but I'm happy to at least push up my first draft schema files any time! I'll start there and we can figure out the Maven part next.