This repository houses data types designed to help parse the data produced by two Terraform commands:
While containing mostly data types, there are also a few helpers to assist with working with the data.
This repository also serves as de facto documentation for the formats produced by these commands. For more details, see the GoDoc.
This library was built for a few specific applications, and is not intended for general purpose use.
The Terraform core team recommends against using terraform-json if your
application has any of the following requirements:
- Forward-compatibility: each version of this library represents a specific snapshot of the Terraform JSON output format, and it often slightly lags behind Terraform itself. The library supports the 1.x compatibility promises but you will need to upgrade the version promptly to use new additions. If you require full compatibility with future Terraform versions, we recommend implementing your own custom decoders for the parts of the JSON format you need.
- Writing JSON output: the structures in this library are not guaranteed to emit JSON data which is semantically equivalent to Terraform itself. If your application must robustly write JSON data to be consumed by systems which expect Terraform's format to be supported, you should implement your own custom encoders.
- Filtering or round-tripping: the Terraform JSON formats are designed to be forwards compatible, and permit new attributes to be added which may safely be ignored by earlier versions of consumers. This library drops unknown attributes, which means it is unsuitable for any application which intends to filter data or read-modify-write data which will be consumed downstream. Any application doing this will silently drop new data from new versions. For this application, you should implement a custom decoder and encoder which preserves any unknown attributes through a round-trip.
When is terraform-json suitable? We recommend using it for applications which
decode the core stable data types and use it directly, and don't attempt to emit
JSON to be consumed by applications which expect the Terraform format.
To reduce dependencies on any of Terraform core's internals, we've made a design decision to make any helpers or libraries that work with the external JSON data external and not a part of the Terraform GitHub repository itself.
While Terraform core will change often and be relatively unstable, this library will see a smaller amount of change. Most of the major changes have already happened leading up to 0.12, so you can expect this library to only see minor incremental changes going forward.
For this reason, terraform show -json and terraform providers schema -json
is the recommended format for working with Terraform data externally, and as
such, if you require any help working with the data in these formats, or even a
reference of how the JSON is formatted, use this repository.