Merge pull request #104 from hashicorp/alisdair/should-i-use-this-library
Update README to explain when not to use this library
diff --git a/README.md b/README.md
index 4a9cd94..462c1a8 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,39 @@
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:
+
+* **Forward-compatibility**: each version of 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 behind Terraform itself. The library supports
+ [the 1.x compatibility promises](https://developer.hashicorp.com/terraform/language/v1-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.
+
+## 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
