Validate cdktf.json to catch simple configuration errors

[ansgarm]

Community Note

• Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request
• Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for issue followers and do not help prioritize the request
• If you are interested in working on this issue or have submitted a pull request, please leave a comment

Description

We had a user report on an issue with the excludeStackIdFromLogicalIds flag in the cdktf.json via the CDK Dev Slack. The flag had been set to "false" (string) instead of false (boolean). As TypeScript treats "false" as a truthy value the setting was interpreted as if true would have been passed.

By validating the cdktf.json against a schema, we could catch such errors without having to do much work.

Furthermore, it would be possible to use somehow publish e.g. a json schema which then can be picked up by editors and offer intellisense when editing the cdktf.json config. For this versioning (e.g. feature flags that change) might be a concern that could make this more complicated.

References

[anden-akkio]

Here's an at least mostly correct one, translated from the spec on this page:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "cdktf.schema.json",
  "type": "object",
  "properties": {
    "app": {
      "type": "string",
      "description": "The command to run in order to synthesize the code to Terraform compatible JSON"
    },
    "language": {
      "type": "string",
      "enum": ["typescript", "python", "csharp", "java", "go"],
      "description": "Target language for building provider or module bindings. Currently supported: `typescript`, `python`, `java`, `csharp`, and `go`"
    },
    "output": {
      "type": "string",
      "default": "cdktf.out",
      "description": "Default: 'cdktf.out'. Where the synthesized JSON should go. Also will be the working directory for Terraform operations"
    },
    "codeMakerOutput": {
      "type": "string",
      "default": ".gen",
      "description": "Default: '.gen'. Path where generated provider bindings will be rendered to."
    },
    "projectId": {
      "type": "string",
      "description": "Default: generated UUID. Unique identifier for the project used to differentiate projects"
    },
    "sendCrashReports": {
      "type": "boolean",
      "default": false,
      "description": "Default: false. Whether to send crash reports to the CDKTF team"
    },
    "terraformProviders": {
      "type": "array",
      "items": {
        "anyOf": [
          { "type": "string" },
          {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "source": { "type": "string" },
              "version": { "type": "string" }
            },
            "required": ["name"]
          }
        ]
      },
      "description": "Terraform Providers to build"
    },
    "terraformModules": {
      "type": "array",
      "items": {
        "anyOf": [
          { "type": "string" },
          {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "source": { "type": "string" },
              "version": { "type": "string" }
            },
            "required": ["name"]
          }
        ]
      },
      "description": "Terraform Modules to build"
    }
  },
  "required": ["app", "language", "terraformProviders", "terraformModules"]
}

You can tell your editor to validate against it by adding a line to your cdktf.json file pointing it towards the schema file (which I have directly adjacent to my cdktf.json):

{
	"$schema": "./cdktf.schema.json",
}

Would of course be great to get an "official" one maintained by Hashicorp, as I doubt I'll update the above if any changes are made.

[icholy]

We have some custom properties in our cdktf.json file which are used by internal tooling. If validation was added, would it be possible to either:

1. Add a dedicated property which can contain arbitrary configuration (a metadata property).
2. Add a prefix (similar to x- properties in swagger) to be used for custom properties. https://swagger.io/docs/specification/v3_0/openapi-extensions/
3. Guarantee that the json schema won't have additionalProperties: false enable.