HashiCorp Terraform 0.12 Preview: Reliable JSON Syntax

This is the eighth post of the series highlighting new features in Terraform 0.12.

As part of the lead up to the release of Terraform 0.12, we are publishing a series of feature preview blog posts. The post this week is on bringing a clear 1:1 mapping between JSON and HCL.

Terraform has accepted JSON as configuration in addition to HCL since version 0.1. However, the implementation of this prior to version 0.12 had many shortcomings. The HCL improvements in Terraform 0.12 include a clear 1:1 mapping between HCL and JSON, including much clearer error messages and support for comments!

These improvements make it easy to work with Terraform using HCL, JSON, or both.

»HCL and JSON

Terraform has supported JSON as an alternate configuration format since its initial release in Terraform 0.1. Further, Terraform has supported mixing JSON and HCL configurations within the same module since version 0.1, as well. Both JSON and HCL are important first-class configuration formats for Terraform.

The JSON mapping in prior versions of Terraform had many shortcomings. In some cases, it felt as though JSON didn't feel like a first class solution in the tool. We have always considered JSON a first class input to Terraform and continue to do so, so a big part of Terraform 0.12 was having a clean 1:1 mapping between HCL and JSON, and ensuring every feature of HCL is supported in JSON.

Terraform 0.12 achieves these goals. In future versions of Terraform, we will also support native tooling to convert HCL to JSON and JSON to HCL cleanly (including comments). This gives additional tooling more power in working with Terraform configurations and also enables people to author configurations in whichever language they feel comfortable.

»Error Message Improvements

In versions prior to 0.12, the configuration mapping to JSON was only weakly specified in documentation, there were many counter-intuitive mapping behaviors, and there was a tendency to silently ignore misshapen constructs that made debugging difficult.

Terraform 0.12 includes a new JSON configuration implementation that is more robust than prior versions to address these limitations. In particular, the JSON-based configuration decoder produces errors in any cases where the input cannot be mapped exactly onto the expected configuration structure.

The example below shows an invalid configuration the error produced in Terraform 0.12:

{
  "variable": {
    "example": "foo"
  }
}

Error: Incorrect JSON value type

  on example.tf.json line 3, in variable:
   3:     "example": "foo"

Either a JSON object or JSON array is required, representing the contents of
one or more "variable" blocks.

Terraform now knows that the top-level name "variable" represents a set of variable blocks in the native syntax, and so it can see that the value of the property "example" should be an object representing the contents of a variable "example" block in HCL. The above example can therefore be corrected by replacing the string value with an object:

{
  "variable": {
    "example": {
      "default": "foo"
    }
  }
}

To properly produce error messages like these, the new JSON decoder is necessarily more strict than in prior versions. As a result, JSON-based configuration generated for prior versions may need to be adjusted slightly to fit within the new constraints.

»Comments in JSON

A big limitation of JSON is the lack of comment support. Terraform 0.12 includes a simplistic form of "comments" in the form of a special key "//" within JSON objects.

The example below shows a comment in a Terraform 0.12 JSON configuration:

{
  "variable": {
    "example": {
      "//": "This property is ignored",
      "default": "foo"
    }
  }
}

In nested block objects, any property named "//" is ignored. While we recommend using the native syntax for hand-written configuration, a JSON comment feature may be useful to include commentary in generated configuration, such as identifying which program generated the file.

»Upgrade Guide

The new JSON parser in Terraform 0.12 is necessarilly more strict than prior versions. Therefore, existing JSON configurations may require changes to work with Terraform 0.12. If you use JSON with Terraform, please run a terraform validate or terraform plan and correct any error messages.

»Next

This was part 8 of the blog post series previewing Terraform 0.12.

The clear 1:1 mapping with JSON will be released in Terraform 0.12, coming later this summer. To learn more about how to upgrade to Terraform 0.12, read the upgrade instructions which will be continuously updated as we get closer to releasing Terraform 0.12. If you have any feedback or concerns about these changes, please communicate with the Terraform team via the public mailing list.