You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Update README to explain when not to use this library
By design, the `terraform-json` library is not always suitable for every application. Its name and prominence may cause those integrating with Terraform to assume otherwise.
This commit expands the README to attempt to clarify situations where the `terraform-json` library is not appropriate, explaining why and what to do instead.
This library was built for a few specific applications, and is not intended for
21
+
general purpose use.
22
+
23
+
The Terraform core team **recommends against** using `terraform-json` if your
24
+
application has any of the following requirements:
25
+
26
+
***Broad version compatibility**: each version this library represents a specific
27
+
snapshot of the [Terraform JSON output format](https://developer.hashicorp.com/terraform/internals/json-format),
28
+
and it often slightly lags Terraform itself. If you require compatibility with
29
+
multiple Terraform versions, we recommend implementing your own custom decoders
30
+
for the parts of the JSON format you need.
31
+
***Writing JSON output**: the structures in this library are not guaranteed to emit
32
+
JSON data which is semantically equivalent to Terraform itself. If your application
33
+
must robustly write JSON data to be consumed by systems which expect Terraform's
34
+
format to be supported, you should implement your own custom encoders.
35
+
***Filtering or round-tripping**: the Terraform JSON formats are designed to be
36
+
forwards compatible, and permit new attributes to be added which may safely be
37
+
ignored by earlier versions of consumers. This library **drops unknown attributes**,
38
+
which means it is unsuitable for any application which intends to filter data
39
+
or read-modify-write data which will be consumed downstream. Any application doing
40
+
this will silently drop new data from new versions. For this applicaiton, you should
41
+
implement a custom decoder and encoder which preserves any unknown attributes
42
+
through a round-trip.
43
+
44
+
When is `terraform-json` suitable? We recommend using it for applications which
45
+
decode the core stable data types and use it directly, and don't attempt to emit
46
+
JSON to be consumed by applications which expect the Terraform format.
47
+
48
+
## Why a separate repository?
19
49
20
50
To reduce dependencies on any of Terraform core's internals, we've made a design
21
51
decision to make any helpers or libraries that work with the external JSON data
0 commit comments