When Terraform plans to make changes, it prints a human-readable summary to the terminal. It can also, when run with `-out=<PATH>`, write a much more detailed binary plan file, which can later be used to apply those changes.
Since the format of plan files isn't suited for use with external tools (and likely never will be), Terraform can output a machine-readable JSON representation of a plan file's changes. It can also convert state files to the same format, to simplify data loading and provide better long-term compatibility.
Use `terraform show -json <FILE>` to generate a JSON representation of a plan or state file. See [the `terraform show` documentation](/docs/commands/show.html) for more details.
-> **Note:** The output includes a `format_version` key, which currently has major version zero to indicate that the format is experimental and subject to change. A future version will assign a non-zero major version and make stronger promises about compatibility. We do not anticipate any significant breaking changes to the format before its first major version, however.
To avoid excessive repetition, we've split the complete format into several discrete sub-objects, described under separate headers. References wrapped in angle brackets (like `<values-representation>`) are placeholders which, in the real output, would be replaced by an instance of the specified sub-object.
- [Block Expressions Representation](#block-expressions-representation) —A sub-object of a configuration representation that describes the expressions nested inside a block.
- [Change Representation](#change-representation) —A sub-object of plan output that describes planned changes to an object.
## State Representation
Because state does not currently have any significant metadata not covered by the common values representation ([described below](#values-representation)), the `<state-representation>` is straightforward:
The extra wrapping object here will allow for any extension we may need to add in future versions of this format.
## Plan Representation
A plan consists of a prior state, the configuration that is being applied to that state, and the set of changes Terraform plans to make to achieve that.
For ease of consumption by callers, the plan representation includes a partial representation of the values in the final state (using a [value representation](#value-representation)), allowing callers to easily analyze the planned outcome using similar code as for analyzing the prior state.
// "planned_values" is a description of what is known so far of the outcome in
// the standard value representation, with any as-yet-unknown values omitted.
"planned_values": <values-representation>,
// "proposed_unknown" is a representation of the attributes, including any
// potentially-unknown attributes. Each value is replaced with "true" or
// "false" depending on whether it is known in the proposed plan.
"proposed_unknown": <values-representation>,
// "variables" is a representation of all the variables provided for the given
// plan. This is structured as a map similar to the output map so we can add
// additional fields in later.
"variables": {
"varname": {
"value": "varvalue"
},
},
// "changes" is a description of the individual change actions that Terraform
// plans to use to move from the prior state to a new state matching the
// configuration.
"resource_changes": [
// Each element of this array describes the action to take
// for one instance object. All resources in the
// configuration are included in this list.
{
// "address" is the full absolute address of the resource instance this
// change applies to, in the same format as addresses in a value
// representation
"address": "module.child.aws_instance.foo[0]",
// "module_address", if set, is the module portion of the above address.
// Omitted if the instance is in the root module.
"module_address": "module.child",
// "mode", "type", "name", and "index" have the same meaning as in a
// value representation.
"mode": "managed",
"type": "aws_instance",
"name": "foo",
"index": 0,
// "deposed", if set, indicates that this action applies to a "deposed"
// object of the given instance rather than to its "current" object.
// Omitted for changes to the current object. "address" and "deposed"
// together form a unique key across all change objects in a particular
// plan. The value is an opaque key representing the specific deposed
// object.
"deposed": "deadbeef",
// "change" describes the change that will be made to the indicated
// object. The <change-representation> is detailed in a section below.
"change": <change-representation>
}
],
// "output_changes" describes the planned changes to the output values of the
// root module.
"output_changes": {
// Keys are the defined output value names.
"foo": {
// "change" describes the change that will be made to the indicated output
// value, using the same representation as for resource changes except
// that the only valid actions values are:
// ["create"]
// ["update"]
// ["delete"]
// In the Terraform CLI 0.12.0 release, Terraform is not yet fully able to
// track changes to output values, so the actions indicated may not be
// fully accurate, but the "after" value will always be correct.
"change": <change-representation>,
}
}
}
```
This overall plan structure, fully expanded, is what will be printed by the `terraform show -json <planfile>` command.
## Values Representation
A values representation is used in both state and plan output to describe current state (which is always complete) and planned state (which omits values not known until apply).
The following example illustrates the structure of a `<values-representation>`:
The translation of attribute and output values is the same intuitive mapping from HCL types to JSON types used by Terraform's [`jsonencode`](/docs/configuration/functions/jsonencode.html) function. This mapping does lose some information: lists, sets, and tuples all lower to JSON arrays while maps and objects both lower to JSON objects. Unknown values and null values are both treated as absent or null.
Only the "current" object for each resource instance is described. "Deposed" objects are not reflected in this structure at all; in plan representations, you can refer to the change representations for further details.
The intent of this structure is to give a caller access to a similar level of detail as is available to expressions within the configuration itself. This common representation is not suitable for all use-cases because it loses information compared to the data structures it is built from. For more complex needs, use the more elaborate changes and configuration representations.
Because the configuration models are produced at a stage prior to expression evaluation, it is not possible to produce a values representation for configuration. Instead, we describe the physical structure of the configuration, giving access to constant values where possible and allowing callers to analyze any references to other objects that are present:
In some cases, it is the entire content of a block (possibly after certain special arguments have already been handled and removed) that must be represented. For that, we have an `<block-expressions-representation>` structure:
For now we expect callers to just hard-code assumptions about the schemas of particular resource types in order to process these expression representations. In a later release we will add new inspection commands to return machine-readable descriptions of the schemas themselves, allowing for more generic handling in programs such as visualization tools.
