From b60f201eeda9006d4b53142c95744d924d27ae4a Mon Sep 17 00:00:00 2001 From: Alisdair McDiarmid Date: Wed, 1 Sep 2021 11:17:13 -0400 Subject: [PATCH] json-output: Release format version 1.0 --- internal/command/jsonplan/plan.go | 2 +- internal/command/jsonprovider/provider.go | 2 +- internal/command/jsonstate/state.go | 2 +- .../testdata/providers-schema/basic/output.json | 2 +- .../testdata/providers-schema/empty/output.json | 4 ++-- .../providers-schema/required/output.json | 2 +- .../testdata/show-json-sensitive/output.json | 4 ++-- .../testdata/show-json-state/basic/output.json | 2 +- .../testdata/show-json-state/empty/output.json | 4 ++-- .../show-json-state/modules/output.json | 2 +- .../sensitive-variables/output.json | 2 +- .../testdata/show-json/basic-create/output.json | 4 ++-- .../testdata/show-json/basic-delete/output.json | 4 ++-- .../testdata/show-json/basic-update/output.json | 4 ++-- .../testdata/show-json/drift/output.json | 4 ++-- .../show-json/module-depends-on/output.json | 2 +- .../testdata/show-json/modules/output.json | 4 ++-- .../show-json/multi-resource-update/output.json | 4 ++-- .../show-json/nested-modules/output.json | 2 +- .../provider-version-no-config/output.json | 4 ++-- .../show-json/provider-version/output.json | 4 ++-- .../show-json/requires-replace/output.json | 4 ++-- .../show-json/sensitive-values/output.json | 4 ++-- .../incorrectmodulename/output.json | 2 +- .../validate-invalid/interpolation/output.json | 2 +- .../missing_defined_var/output.json | 2 +- .../validate-invalid/missing_quote/output.json | 2 +- .../validate-invalid/missing_var/output.json | 2 +- .../multiple_modules/output.json | 2 +- .../multiple_providers/output.json | 2 +- .../multiple_resources/output.json | 2 +- .../testdata/validate-invalid/output.json | 2 +- .../validate-invalid/outputs/output.json | 2 +- .../command/testdata/validate-valid/output.json | 2 +- internal/command/views/validate.go | 2 +- .../docs/cli/commands/providers/schema.html.md | 15 +++++++++++++-- website/docs/cli/commands/validate.html.md | 17 ++++++++++++----- website/docs/internals/json-format.html.md | 15 +++++++++++++-- 38 files changed, 86 insertions(+), 57 deletions(-) diff --git a/internal/command/jsonplan/plan.go b/internal/command/jsonplan/plan.go index 1b90daf2d..b1d488156 100644 --- a/internal/command/jsonplan/plan.go +++ b/internal/command/jsonplan/plan.go @@ -22,7 +22,7 @@ import ( // FormatVersion represents the version of the json format and will be // incremented for any change to this format that requires changes to a // consuming parser. -const FormatVersion = "0.2" +const FormatVersion = "1.0" // Plan is the top-level representation of the json format of a plan. It includes // the complete config and current state. diff --git a/internal/command/jsonprovider/provider.go b/internal/command/jsonprovider/provider.go index b507bc242..4487db498 100644 --- a/internal/command/jsonprovider/provider.go +++ b/internal/command/jsonprovider/provider.go @@ -9,7 +9,7 @@ import ( // FormatVersion represents the version of the json format and will be // incremented for any change to this format that requires changes to a // consuming parser. -const FormatVersion = "0.2" +const FormatVersion = "1.0" // providers is the top-level object returned when exporting provider schemas type providers struct { diff --git a/internal/command/jsonstate/state.go b/internal/command/jsonstate/state.go index 341040d2d..46532875c 100644 --- a/internal/command/jsonstate/state.go +++ b/internal/command/jsonstate/state.go @@ -18,7 +18,7 @@ import ( // FormatVersion represents the version of the json format and will be // incremented for any change to this format that requires changes to a // consuming parser. -const FormatVersion = "0.2" +const FormatVersion = "1.0" // state is the top-level representation of the json format of a terraform // state. diff --git a/internal/command/testdata/providers-schema/basic/output.json b/internal/command/testdata/providers-schema/basic/output.json index f14786c3e..dfac55b38 100644 --- a/internal/command/testdata/providers-schema/basic/output.json +++ b/internal/command/testdata/providers-schema/basic/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.2", + "format_version": "1.0", "provider_schemas": { "registry.terraform.io/hashicorp/test": { "provider": { diff --git a/internal/command/testdata/providers-schema/empty/output.json b/internal/command/testdata/providers-schema/empty/output.json index 12d30d201..381450cad 100644 --- a/internal/command/testdata/providers-schema/empty/output.json +++ b/internal/command/testdata/providers-schema/empty/output.json @@ -1,3 +1,3 @@ { - "format_version": "0.2" -} \ No newline at end of file + "format_version": "1.0" +} diff --git a/internal/command/testdata/providers-schema/required/output.json b/internal/command/testdata/providers-schema/required/output.json index f14786c3e..dfac55b38 100644 --- a/internal/command/testdata/providers-schema/required/output.json +++ b/internal/command/testdata/providers-schema/required/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.2", + "format_version": "1.0", "provider_schemas": { "registry.terraform.io/hashicorp/test": { "provider": { diff --git a/internal/command/testdata/show-json-sensitive/output.json b/internal/command/testdata/show-json-sensitive/output.json index 5f22c4ccf..206fbb7f6 100644 --- a/internal/command/testdata/show-json-sensitive/output.json +++ b/internal/command/testdata/show-json-sensitive/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.2", + "format_version": "1.0", "variables": { "test_var": { "value": "bar" @@ -66,7 +66,7 @@ } }, "prior_state": { - "format_version": "0.2", + "format_version": "1.0", "values": { "outputs": { "test": { diff --git a/internal/command/testdata/show-json-state/basic/output.json b/internal/command/testdata/show-json-state/basic/output.json index 3087ad118..229fa00e7 100644 --- a/internal/command/testdata/show-json-state/basic/output.json +++ b/internal/command/testdata/show-json-state/basic/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.2", + "format_version": "1.0", "terraform_version": "0.12.0", "values": { "root_module": { diff --git a/internal/command/testdata/show-json-state/empty/output.json b/internal/command/testdata/show-json-state/empty/output.json index 12d30d201..381450cad 100644 --- a/internal/command/testdata/show-json-state/empty/output.json +++ b/internal/command/testdata/show-json-state/empty/output.json @@ -1,3 +1,3 @@ { - "format_version": "0.2" -} \ No newline at end of file + "format_version": "1.0" +} diff --git a/internal/command/testdata/show-json-state/modules/output.json b/internal/command/testdata/show-json-state/modules/output.json index eeee8f6cf..eba163bdb 100644 --- a/internal/command/testdata/show-json-state/modules/output.json +++ b/internal/command/testdata/show-json-state/modules/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.2", + "format_version": "1.0", "terraform_version": "0.12.0", "values": { "outputs": { diff --git a/internal/command/testdata/show-json-state/sensitive-variables/output.json b/internal/command/testdata/show-json-state/sensitive-variables/output.json index b133aeef1..60503cd3a 100644 --- a/internal/command/testdata/show-json-state/sensitive-variables/output.json +++ b/internal/command/testdata/show-json-state/sensitive-variables/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.2", + "format_version": "1.0", "terraform_version": "0.14.0", "values": { "root_module": { diff --git a/internal/command/testdata/show-json/basic-create/output.json b/internal/command/testdata/show-json/basic-create/output.json index 3474443ed..d1b8aae53 100644 --- a/internal/command/testdata/show-json/basic-create/output.json +++ b/internal/command/testdata/show-json/basic-create/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.2", + "format_version": "1.0", "variables": { "test_var": { "value": "bar" @@ -57,7 +57,7 @@ } }, "prior_state": { - "format_version": "0.2", + "format_version": "1.0", "values": { "outputs": { "test": { diff --git a/internal/command/testdata/show-json/basic-delete/output.json b/internal/command/testdata/show-json/basic-delete/output.json index 9ebea2058..8a0018cd5 100644 --- a/internal/command/testdata/show-json/basic-delete/output.json +++ b/internal/command/testdata/show-json/basic-delete/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.2", + "format_version": "1.0", "variables": { "test_var": { "value": "bar" @@ -88,7 +88,7 @@ } }, "prior_state": { - "format_version": "0.2", + "format_version": "1.0", "values": { "outputs": { "test": { diff --git a/internal/command/testdata/show-json/basic-update/output.json b/internal/command/testdata/show-json/basic-update/output.json index 2b8bc25e3..e4b473142 100644 --- a/internal/command/testdata/show-json/basic-update/output.json +++ b/internal/command/testdata/show-json/basic-update/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.2", + "format_version": "1.0", "variables": { "test_var": { "value": "bar" @@ -68,7 +68,7 @@ } }, "prior_state": { - "format_version": "0.2", + "format_version": "1.0", "values": { "outputs": { "test": { diff --git a/internal/command/testdata/show-json/drift/output.json b/internal/command/testdata/show-json/drift/output.json index 7badb45e5..55c9e3f71 100644 --- a/internal/command/testdata/show-json/drift/output.json +++ b/internal/command/testdata/show-json/drift/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.2", + "format_version": "1.0", "planned_values": { "root_module": { "resources": [ @@ -105,7 +105,7 @@ } ], "prior_state": { - "format_version": "0.2", + "format_version": "1.0", "values": { "root_module": { "resources": [ diff --git a/internal/command/testdata/show-json/module-depends-on/output.json b/internal/command/testdata/show-json/module-depends-on/output.json index cc7ed679f..d02efaa22 100644 --- a/internal/command/testdata/show-json/module-depends-on/output.json +++ b/internal/command/testdata/show-json/module-depends-on/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.2", + "format_version": "1.0", "terraform_version": "0.13.1-dev", "planned_values": { "root_module": { diff --git a/internal/command/testdata/show-json/modules/output.json b/internal/command/testdata/show-json/modules/output.json index 440bebbff..4ed0ea45d 100644 --- a/internal/command/testdata/show-json/modules/output.json +++ b/internal/command/testdata/show-json/modules/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.2", + "format_version": "1.0", "planned_values": { "outputs": { "test": { @@ -74,7 +74,7 @@ } }, "prior_state": { - "format_version": "0.2", + "format_version": "1.0", "values": { "outputs": { "test": { diff --git a/internal/command/testdata/show-json/multi-resource-update/output.json b/internal/command/testdata/show-json/multi-resource-update/output.json index d84bc5b08..ba557de69 100644 --- a/internal/command/testdata/show-json/multi-resource-update/output.json +++ b/internal/command/testdata/show-json/multi-resource-update/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.2", + "format_version": "1.0", "terraform_version": "0.13.0", "variables": { "test_var": { @@ -127,7 +127,7 @@ } }, "prior_state": { - "format_version": "0.2", + "format_version": "1.0", "terraform_version": "0.13.0", "values": { "outputs": { diff --git a/internal/command/testdata/show-json/nested-modules/output.json b/internal/command/testdata/show-json/nested-modules/output.json index 80e7ae358..359ea9ae1 100644 --- a/internal/command/testdata/show-json/nested-modules/output.json +++ b/internal/command/testdata/show-json/nested-modules/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.2", + "format_version": "1.0", "planned_values": { "root_module": { "child_modules": [ diff --git a/internal/command/testdata/show-json/provider-version-no-config/output.json b/internal/command/testdata/show-json/provider-version-no-config/output.json index 64b93ec75..6a8b1f451 100644 --- a/internal/command/testdata/show-json/provider-version-no-config/output.json +++ b/internal/command/testdata/show-json/provider-version-no-config/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.2", + "format_version": "1.0", "variables": { "test_var": { "value": "bar" @@ -57,7 +57,7 @@ } }, "prior_state": { - "format_version": "0.2", + "format_version": "1.0", "values": { "outputs": { "test": { diff --git a/internal/command/testdata/show-json/provider-version/output.json b/internal/command/testdata/show-json/provider-version/output.json index b5369806e..11fd3bd64 100644 --- a/internal/command/testdata/show-json/provider-version/output.json +++ b/internal/command/testdata/show-json/provider-version/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.2", + "format_version": "1.0", "variables": { "test_var": { "value": "bar" @@ -57,7 +57,7 @@ } }, "prior_state": { - "format_version": "0.2", + "format_version": "1.0", "values": { "outputs": { "test": { diff --git a/internal/command/testdata/show-json/requires-replace/output.json b/internal/command/testdata/show-json/requires-replace/output.json index 077d900b1..e71df784f 100644 --- a/internal/command/testdata/show-json/requires-replace/output.json +++ b/internal/command/testdata/show-json/requires-replace/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.2", + "format_version": "1.0", "planned_values": { "root_module": { "resources": [ @@ -48,7 +48,7 @@ } ], "prior_state": { - "format_version": "0.2", + "format_version": "1.0", "values": { "root_module": { "resources": [ diff --git a/internal/command/testdata/show-json/sensitive-values/output.json b/internal/command/testdata/show-json/sensitive-values/output.json index 7cbc9ccf0..d7e4719c7 100644 --- a/internal/command/testdata/show-json/sensitive-values/output.json +++ b/internal/command/testdata/show-json/sensitive-values/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.2", + "format_version": "1.0", "variables": { "test_var": { "value": "boop" @@ -69,7 +69,7 @@ } }, "prior_state": { - "format_version": "0.2", + "format_version": "1.0", "values": { "outputs": { "test": { diff --git a/internal/command/testdata/validate-invalid/incorrectmodulename/output.json b/internal/command/testdata/validate-invalid/incorrectmodulename/output.json index 0c2ce68ab..f144313fa 100644 --- a/internal/command/testdata/validate-invalid/incorrectmodulename/output.json +++ b/internal/command/testdata/validate-invalid/incorrectmodulename/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.1", + "format_version": "1.0", "valid": false, "error_count": 4, "warning_count": 0, diff --git a/internal/command/testdata/validate-invalid/interpolation/output.json b/internal/command/testdata/validate-invalid/interpolation/output.json index 7845ec0f4..2843b1912 100644 --- a/internal/command/testdata/validate-invalid/interpolation/output.json +++ b/internal/command/testdata/validate-invalid/interpolation/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.1", + "format_version": "1.0", "valid": false, "error_count": 2, "warning_count": 0, diff --git a/internal/command/testdata/validate-invalid/missing_defined_var/output.json b/internal/command/testdata/validate-invalid/missing_defined_var/output.json index c2a57c5e6..40258a98c 100644 --- a/internal/command/testdata/validate-invalid/missing_defined_var/output.json +++ b/internal/command/testdata/validate-invalid/missing_defined_var/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.1", + "format_version": "1.0", "valid": true, "error_count": 0, "warning_count": 0, diff --git a/internal/command/testdata/validate-invalid/missing_quote/output.json b/internal/command/testdata/validate-invalid/missing_quote/output.json index cdf99d8b2..87aeca8b7 100644 --- a/internal/command/testdata/validate-invalid/missing_quote/output.json +++ b/internal/command/testdata/validate-invalid/missing_quote/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.1", + "format_version": "1.0", "valid": false, "error_count": 1, "warning_count": 0, diff --git a/internal/command/testdata/validate-invalid/missing_var/output.json b/internal/command/testdata/validate-invalid/missing_var/output.json index 2a4e0be71..6f0b9d5d4 100644 --- a/internal/command/testdata/validate-invalid/missing_var/output.json +++ b/internal/command/testdata/validate-invalid/missing_var/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.1", + "format_version": "1.0", "valid": false, "error_count": 1, "warning_count": 0, diff --git a/internal/command/testdata/validate-invalid/multiple_modules/output.json b/internal/command/testdata/validate-invalid/multiple_modules/output.json index 4cd6dfb9f..1aeaf929a 100644 --- a/internal/command/testdata/validate-invalid/multiple_modules/output.json +++ b/internal/command/testdata/validate-invalid/multiple_modules/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.1", + "format_version": "1.0", "valid": false, "error_count": 1, "warning_count": 0, diff --git a/internal/command/testdata/validate-invalid/multiple_providers/output.json b/internal/command/testdata/validate-invalid/multiple_providers/output.json index 63eb2d193..309cf0ea7 100644 --- a/internal/command/testdata/validate-invalid/multiple_providers/output.json +++ b/internal/command/testdata/validate-invalid/multiple_providers/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.1", + "format_version": "1.0", "valid": false, "error_count": 1, "warning_count": 0, diff --git a/internal/command/testdata/validate-invalid/multiple_resources/output.json b/internal/command/testdata/validate-invalid/multiple_resources/output.json index 33d505228..ded584e68 100644 --- a/internal/command/testdata/validate-invalid/multiple_resources/output.json +++ b/internal/command/testdata/validate-invalid/multiple_resources/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.1", + "format_version": "1.0", "valid": false, "error_count": 1, "warning_count": 0, diff --git a/internal/command/testdata/validate-invalid/output.json b/internal/command/testdata/validate-invalid/output.json index 663fe0153..732548539 100644 --- a/internal/command/testdata/validate-invalid/output.json +++ b/internal/command/testdata/validate-invalid/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.1", + "format_version": "1.0", "valid": false, "error_count": 1, "warning_count": 0, diff --git a/internal/command/testdata/validate-invalid/outputs/output.json b/internal/command/testdata/validate-invalid/outputs/output.json index d05ed4b77..f774b458b 100644 --- a/internal/command/testdata/validate-invalid/outputs/output.json +++ b/internal/command/testdata/validate-invalid/outputs/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.1", + "format_version": "1.0", "valid": false, "error_count": 2, "warning_count": 0, diff --git a/internal/command/testdata/validate-valid/output.json b/internal/command/testdata/validate-valid/output.json index c2a57c5e6..40258a98c 100644 --- a/internal/command/testdata/validate-valid/output.json +++ b/internal/command/testdata/validate-valid/output.json @@ -1,5 +1,5 @@ { - "format_version": "0.1", + "format_version": "1.0", "valid": true, "error_count": 0, "warning_count": 0, diff --git a/internal/command/views/validate.go b/internal/command/views/validate.go index 1e597277a..08ce913f8 100644 --- a/internal/command/views/validate.go +++ b/internal/command/views/validate.go @@ -81,7 +81,7 @@ func (v *ValidateJSON) Results(diags tfdiags.Diagnostics) int { // FormatVersion represents the version of the json format and will be // incremented for any change to this format that requires changes to a // consuming parser. - const FormatVersion = "0.1" + const FormatVersion = "1.0" type Output struct { FormatVersion string `json:"format_version"` diff --git a/website/docs/cli/commands/providers/schema.html.md b/website/docs/cli/commands/providers/schema.html.md index e97e50f23..2a3dddc13 100644 --- a/website/docs/cli/commands/providers/schema.html.md +++ b/website/docs/cli/commands/providers/schema.html.md @@ -23,7 +23,18 @@ The list of available flags are: Please note that, at this time, the `-json` flag is a _required_ option. In future releases, this command will be extended to allow for additional options. --> **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. +The output includes a `format_version` key, which as of Terraform 1.1.0 has +value `"1.0"`. The semantics of this version are: + +- We will increment the minor version, e.g. `"1.1"`, for backward-compatible + changes or additions. Ignore any object properties with unrecognized names to + remain forward-compatible with future minor versions. +- We will increment the major version, e.g. `"2.0"`, for changes that are not + backward-compatible. Reject any input which reports an unsupported major + version. + +We will introduce new major versions only within the bounds of +[the Terraform 1.0 Compatibility Promises](https://www.terraform.io/docs/language/v1-compatibility-promises.html). ## Format Summary @@ -41,7 +52,7 @@ The JSON output format consists of the following objects and sub-objects: ```javascript { - "format_version": "0.1", + "format_version": "1.0", // "provider_schemas" describes the provider schemas for all // providers throughout the configuration tree. diff --git a/website/docs/cli/commands/validate.html.md b/website/docs/cli/commands/validate.html.md index 583186e3d..e81da01b2 100644 --- a/website/docs/cli/commands/validate.html.md +++ b/website/docs/cli/commands/validate.html.md @@ -57,11 +57,18 @@ to the JSON output setting. For that reason, external software consuming Terraform's output should be prepared to find data on stdout that _isn't_ valid JSON, which it should then treat as a generic error case. -**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. +The output includes a `format_version` key, which as of Terraform 1.1.0 has +value `"1.0"`. The semantics of this version are: + +- We will increment the minor version, e.g. `"1.1"`, for backward-compatible + changes or additions. Ignore any object properties with unrecognized names to + remain forward-compatible with future minor versions. +- We will increment the major version, e.g. `"2.0"`, for changes that are not + backward-compatible. Reject any input which reports an unsupported major + version. + +We will introduce new major versions only within the bounds of +[the Terraform 1.0 Compatibility Promises](https://www.terraform.io/docs/language/v1-compatibility-promises.html). In the normal case, Terraform will print a JSON object to the standard output stream. The top-level JSON object will have the following properties: diff --git a/website/docs/internals/json-format.html.md b/website/docs/internals/json-format.html.md index 9a3efeff5..b5f8daab3 100644 --- a/website/docs/internals/json-format.html.md +++ b/website/docs/internals/json-format.html.md @@ -16,7 +16,18 @@ Since the format of plan files isn't suited for use with external tools (and lik Use `terraform show -json ` to generate a JSON representation of a plan or state file. See [the `terraform show` documentation](/docs/cli/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. +The output includes a `format_version` key, which as of Terraform 1.1.0 has +value `"1.0"`. The semantics of this version are: + +- We will increment the minor version, e.g. `"1.1"`, for backward-compatible + changes or additions. Ignore any object properties with unrecognized names to + remain forward-compatible with future minor versions. +- We will increment the major version, e.g. `"2.0"`, for changes that are not + backward-compatible. Reject any input which reports an unsupported major + version. + +We will introduce new major versions only within the bounds of +[the Terraform 1.0 Compatibility Promises](https://www.terraform.io/docs/language/v1-compatibility-promises.html). ## Format Summary @@ -60,7 +71,7 @@ For ease of consumption by callers, the plan representation includes a partial r ```javascript { - "format_version": "0.2", + "format_version": "1.0", // "prior_state" is a representation of the state that the configuration is // being applied to, using the state representation described above.