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.
diff --git a/README.md b/README.md
index 4a9cd94..1971d1a 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,37 @@
by these commands. For more details, see the
[GoDoc](https://godoc.org/github.com/hashicorp/terraform-json).
-## Why a Separate Repository?
+## Should I use this library?
+
+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:
+
+* **Broad version compatibility**: each version this library represents a specific
+ snapshot of the [Terraform JSON output format](https://developer.hashicorp.com/terraform/internals/json-format),
+ and it often slightly lags Terraform itself. If you require compatibility with
+ multiple 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 applicaiton, 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.
+
+## Why a separate repository?
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
