terraform-json

The terraform-json library provides Go data types designed to parse the JSON output produced by specific Terraform commands. It serves as both a parsing library and a de facto documentation reference for the Terraform JSON formats.

It is primarily intended for decoding the following command outputs:

• terraform show -json
• terraform providers schema -json

Use this library when you need to decode core stable data types for inspection or analysis, but do not intend to emit JSON that must strictly match Terraform's internal semantic format.

To use the Round-Trip Dumper/Diagnostic Tool, you can build the binary using Go. This tool loads a Terraform plan JSON file and immediately dumps it back to stdout, which is useful for troubleshooting large parsing errors.

To build the binary, run the following command from the cmd/round-trip-dumper directory:

go build ./

If you do not need a permanent binary, you can run the tool directly using go run from the cmd/round-trip-dumper directory.

go run .

The ProviderSchemas struct acts as a registry for all schemas used in a configuration. It contains:

• FormatVersion: The version of the JSON plan format.
• Schemas: A map of provider types (e.g., "hashicorp/aws") to their respective ProviderSchema.

type ProviderSchemas struct {
	FormatVersion string                       `json:"format_version,omitempty"` 
	Schemas       map[string]*ProviderSchema `json:"provider_schemas,omitempty"` 
}

Terraform schemas are hierarchical. A Schema contains a Block, which contains Attributes and NestedBlocks (of type SchemaBlockType).

• SchemaBlock: Contains Attributes (key-value pairs) and NestedBlocks (complex structures).
• SchemaAttribute: Defines a single value. It uses either AttributeType (a cty.Type) or AttributeNestedType (for complex nested structures). It includes metadata like Required, Optional, Computed, Sensitive, and Deprecated.
• SchemaBlockType: Defines how nested blocks behave using a NestingMode.

The StateValues type provides a common representation for both existing state and planned state. It contains:

• Outputs: A map of StateOutput objects.
• RootModule: A pointer to the StateModule representing the root of the configuration.

StateModule can represent the root or child modules and contains a list of Resources and ChildModules.

// Accessing the root module and its resources
root := state.Values.RootModule
for _, resource := range root.Resources {
    fmt.Printf("Resource Address: %s\n", resource.Address)
}

If a resource is being imported during the plan, the ResourceChange.Change object will contain an Importing field. This field contains:

• ID: The original ID used to target the import.
• Unknown: A boolean indicating if the ID was unknown at plan time.
• Identity: The identity used to target the resource for import.

In Terraform, there is a distinction between an explicit null and a value that is unknown because it depends on references that cannot be resolved at parse-time.

• Explicit Null: Represented by a nil value in the ConstantValue field of ExpressionData.
• Unknown Value: Represented by the UnknownConstantValue singleton. When unmarshaling JSON, if the references array is non-empty, the library automatically sets ConstantValue to UnknownConstantValue to signal that the value is unresolved.

if expr.ConstantValue == tfjson.UnknownConstantValue {
	// The value is unknown due to unresolved references
} else if expr.ConstantValue == nil {
	// The value is an explicit null
}

The Plan struct is the root object representing the entire output of a Terraform plan. Key fields include:

• FormatVersion: The version of the JSON plan format.
• TerraformVersion: The version of Terraform that generated the plan.
• Variables: A map of top-level PlanVariable objects.
• PlannedValues: The state representation after changes are applied.
• ResourceChanges: A list of ResourceChange objects describing actions for resources and data sources.
• ResourceDrift: Changes resulting from resource drift.
• DeferredChanges: Changes that are deferred (e.g., due to unknown values).
• OutputChanges: Changes to Terraform outputs.
• PriorState: The state before the plan operation.
• Config: The Terraform configuration used.

The tfjson package provides types to represent Terraform resource change operations.

• Action: A string type representing a single operation (e.g., create, update).
• Actions: A slice of Action types. Because some Terraform operations are composite (like a replacement), you should use the Actions type and its helper methods to determine the nature of a change rather than inspecting individual actions manually.

Common single actions include ActionCreate, ActionUpdate, and ActionDelete. Composite operations like replacement are represented as a sequence of actions within the Actions slice.

import "github.com/hashicorp/terraform-json"

// Example of checking for a replacement operation
var change tfjson.Actions = tfjson.Actions{tfjson.ActionDelete, tfjson.ActionCreate}

if change.Replace() {
    // Handle resource replacement logic
}

A ResourceChange describes how a specific resource (identified by Address, Type, and Name) will move from its prior state to a new state.

Each ResourceChange contains a Change object which includes:

• Actions: The specific operations to perform (e.g., create, read, update, delete).
• Before / After: The state of the resource before and after the action.
• AfterUnknown: A map indicating which values in the After state are unknown until apply time.
• BeforeSensitive / AfterSensitive: Versions of the state where sensitive values are masked to prevent accidental exposure.
• ReplacePaths: Paths to attributes causing a resource replacement instead of a simple update.