Public JSON Schema for `cdk.json`

[mrgrain]

cdk.json is a file that can exist in two places:

• the current apps root directory $PWD/cdk.json
• the user's home directory ~/cdk.json

The file plays an essential role in the CDK workflow. It holds the app command, i.e. instructions for the CDK Toolkit on how to synth the user's cdk app. It also holds feature flags and some other settings for the app.

However, today the allowed contents of this file are not well-defined. The best place we have is in the guide: https://docs.aws.amazon.com/cdk/v2/guide/cli.html#cli-config but this is not a prescriptive definition. E.g. the guide claims notices is supported but this is not currently working #724. The Toolkit code base does not formally define which values are supported and which not. This probably contributed to #724 as well.

---

Instead, I am proposing we will maintain and publish a public JSON Schema for allows values in the cdk.json.
The initial contents of the schema should be:

• any settings as documented in the guide
• any currently working settings, to be verified by code exploration
• the types

With this schema, we can do the following things in the CDK Toolkit:

• When loading cdk.json files, parse and/or validate contents and warn on unexpected values.
• Write automated unit tests that based on the schema, ensure any valid fields from cdk.json will make it into the user configuration object.
• Update Toolkit CLI code to only allow access to CLI options through the user config objects

---

Initially, the json schema will be manually created. In future we can auto-generate this from a common data source and extend support to all CLI options. However there are some unique challenges to be solved to support that, let's get started with something. We might also need allow users to put custom values somewhere without producing a warning, as we have seen customers adding their own details into the file.