Demonstrate using tooling to produce JSON schema files enriched with descriptions

[jack-berg]

Alternative to #400 which uses tooling to produce JSON schema files enriched with descriptions from the meta schema.

Main advantage here is that we can include descriptions which are a combination of bits of information from the meta schema:

• description from meta_schema_types.yaml
• isSdkExtensionPlugin from metah_schema_types.yaml
• Default and null behavior (see Split out defaultBehavior and nullBehavior from description in the meta schema #357)
• (Possibly) snippets (see Snippets #397)

[jack-berg]

Showing these output files for demonstration purposes, but if we go in this direction, maybe we don't check these into git, but include them as release artifacts

[codeboten]

after thinking about this more, i think we would definitely want to have whatever the current version is checked in

[jack-berg]

I could also setup the tooling to directly modify the schema JSON files in place. This would also help ensure consistent formatting (i.e. indenting), and is akin to gofmt, prettier, spotless.

[jack-berg]

A short script which:

• Reads all the JSON schema files into memory
• Walks through all the types and properties from the meta schema and for each:
  • Finds the appropriate JSON schema file, type definition, and property definition, and updates the JSON to set description from the meta schema

[codeboten]

I would suggest that if this is the desired direction, we should remove the json schema and represent the data in yaml as the source of truth.

One problem with moving away from the source schema altogether is that the yaml and tooling then needs to be able to represent any relationship that json schema does, which may cost more down the road if we find new ways to use the schema that we have yet to implement.

Having both yaml and json schema be combined to produce another json makes it harder to make understand how this all works together.

[codeboten]

after thinking about this more, i think we would definitely want to have whatever the current version is checked in

[jack-berg]

One thing to think about is that even if we embed description in the JSON schema, I don't think we'll fully be able to get rid of the meta schema files, since the meta_schema_language_{language}.yaml files have significant maintenance benefits compared to embedding the information directly in the JSON schema.

I would suggest that if this is the desired direction, we should remove the json schema and represent the data in yaml as the source of truth.

In this case, we'd need to publish the schema in JSON format. Correct?

One problem with moving away from the source schema altogether is that the yaml and tooling then needs to be able to represent any relationship that json schema does

Not sure I'm following. Can you elaborate?