No proper documentation for .tf.json format

[rahulkp220]

Hi, This isn't a bug, but a concern. I am using Terraform for a project in which I am provisioning Azure , using python and generating terraform compatible JSON for the same. The main problem is there is no specific documentation available for .tf.json format which can be looked upon. The way I am doing it right now is to create a .tf file using HCL and then using a hcltool which converts the file into JSON , which I then use as a reference for my development script.

The link https://www.terraform.io/docs/configuration/syntax.html isn't much helpful.

[apparentlymart]

Hi @rahulkp220! Thanks for this feedback.

We're aware that right now the JSON format is a bit of a second-class citizen, since indeed it is not well documented, and it has some counter-intuitive behaviors that result from the mapping to the HCL model.

We are planning to make the JSON format more robust and better-defined as part of the in-progress configuration language improvements. After that, the JSON format will have more predictable behavior and we can document that behavior.

The configuration language improvements are a large, multi-step project, so it's not yet certain when different parts of it will be ready, but we'll try to come back and update here we have updates in this area.

[nbering]

@apparentlymart That's great to know! I currently use the JSON format myself (it made it easier to create simple helper scripts since almost every language has JSON parsing available or even built-in. I can echo that the documentation wasn't great to figure it out. I managed to muddle through and figure out how it worked based on the one or two paragraphs that were available to describe how the JSON format maps to the same model that HCL represents.

[rahulkp220]

Great! In my opinion having HCL is good, but from a developer's perspective playing around with a JSON is far more easier as its widely known and accepted. Also there isn't any good parser available for parsing HCL in Python which can indeed be helpful to generate the same syntax from code as and when needed.

[apparentlymart]

In the mean time you might find the work-in-progress spec for the new implementation interesting. The details here are subject to change before we ship it (and, importantly, the details here don't necessarily describe the current implementation exactly) but it shows what we're aiming to achieve here.

Notably we're constraining things slightly more than in the current implementation to remove some of the ambiguities that make certain constructs hard or impossible to express in JSON today. As a result, existing JSON config files may need to be adjusted slightly to work within the new constraints, but in return we'll get something that's actually predictable and well-defined.

[rahulkp220]

@apparentlymart Ohkay, thanks for that link. Will have a look at that and may be I get can something helpful from it.

[blast-hardcheese]

Any updates to this? Is HCL2 backwards compatible with what's currently in Terraform? If not, are there any other resources available for those working directly with .tf.json?

[apparentlymart]

Many of the problems with Terraform's current JSON support result from how liberal it is in trying to interpret all sorts of weird constructions as blocks vs. attributes. In order to make its behavior predictable it was necessary to apply some constraints to it, and so I'm sure there are some forms that were possible in the old JSON parser that will be rejected by the new, but the new form was specified by referring to examples we had published in the past and examples seen in the wild and so we expect it to be compatible with a majority of "real-world" JSON configurations for Terraform.

For those rare cases that are doing something more unusual that is no longer supported, the new parser produces contextual errors when the input doesn't conform to expectations, which will allow these problems to be immediately detected (rather than silently causing strange behavior) and revised.

Since my last comment, we've written a first draft of the new JSON syntax documentation, giving a Terraform-oriented description of the key parts of the general spec I linked previously. We're planning to include this in the next major release. While some details may change before we get there (if, for example, we find that one of the decisions made here is contrary to the goal of being compatible with most existing configurations), this shows the intended direction and so hopefully gives a sense of which JSON structures are considered "idiomatic" in the new implementation, and thus (by omission) what might be considered more esoteric and might require some revisions after the next major release.

(Since that page is a GitHub rendering of some Markdown ultimately destined for the Terraform website, many of the links will unfortunately not work correctly in GitHub's rendering due to different URL styles. The rest of the documentation about the Terraform language is also being revised for the next major release, so this new doc page is assuming some terminology and notation introduced on other pages that are not yet released, but hopefully the intent is clear.)

[blast-hardcheese]

@apparentlymart Excellent! So, if I read this correctly, HCL2's JSON support is a clarified subset of HCL1's? Basing my project off HCL2's JSON representation should be sufficient?

[apparentlymart]

Hi all!

I'm pleased to report that the draft docs I mentioned earlier have now been merged into master and will be published on the website in conjunction with the forthcoming v0.12.0 final release. Since this is now landed in master, I'm going to close this out. Thanks for raising this, and for your patience while we worked through integrating the new JSON parser, etc.

[ghost]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.

If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.