> For the complete documentation index, see [llms.txt](https://docs.ionos.com/cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ionos.com/cloud/tools-terraform/vendor/github.com/hashicorp/terraform-json.md).

# terraform-json

[![GoDoc](https://godoc.org/github.com/hashicorp/terraform-json?status.svg)](https://godoc.org/github.com/hashicorp/terraform-json)

This repository houses data types designed to help parse the data produced by two [Terraform](https://www.terraform.io/) commands:

* [`terraform show -json`](https://www.terraform.io/docs/commands/show.html#json-output)
* [`terraform providers schema -json`](https://www.terraform.io/docs/commands/providers/schema.html#json)

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](https://godoc.org/github.com/hashicorp/terraform-json).

## 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 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ionos.com/cloud/tools-terraform/vendor/github.com/hashicorp/terraform-json.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
