Merge pull request #28108 from hashicorp/alisdair/validate-json-format-version

cli: Add format version to validate -json output

command/testdata/validate-invalid/incorrectmodulename/output.json

@@ -1,4 +1,5 @@
 {
+  "format_version": "0.1",
   "valid": false,
   "error_count": 6,
   "warning_count": 0,

command/testdata/validate-invalid/interpolation/output.json

@@ -1,4 +1,5 @@
 {
+  "format_version": "0.1",
   "valid": false,
   "error_count": 2,
   "warning_count": 0,

command/testdata/validate-invalid/missing_defined_var/output.json

@@ -1,4 +1,5 @@
 {
+  "format_version": "0.1",
   "valid": true,
   "error_count": 0,
   "warning_count": 0,

command/testdata/validate-invalid/missing_quote/output.json

@@ -1,4 +1,5 @@
 {
+  "format_version": "0.1",
   "valid": false,
   "error_count": 1,
   "warning_count": 0,

command/testdata/validate-invalid/missing_var/output.json

@@ -1,4 +1,5 @@
 {
+  "format_version": "0.1",
   "valid": false,
   "error_count": 1,
   "warning_count": 0,

command/testdata/validate-invalid/multiple_modules/output.json

@@ -1,4 +1,5 @@
 {
+  "format_version": "0.1",
   "valid": false,
   "error_count": 2,
   "warning_count": 0,

command/testdata/validate-invalid/multiple_providers/output.json

@@ -1,4 +1,5 @@
 {
+  "format_version": "0.1",
   "valid": false,
   "error_count": 1,
   "warning_count": 0,

command/testdata/validate-invalid/multiple_resources/output.json

@@ -1,4 +1,5 @@
 {
+  "format_version": "0.1",
   "valid": false,
   "error_count": 1,
   "warning_count": 0,

command/testdata/validate-invalid/output.json

@@ -1,4 +1,5 @@
 {
+  "format_version": "0.1",
   "valid": false,
   "error_count": 1,
   "warning_count": 0,

command/testdata/validate-invalid/outputs/output.json

@@ -1,4 +1,5 @@
 {
+  "format_version": "0.1",
   "valid": false,
   "error_count": 2,
   "warning_count": 0,

command/testdata/validate-valid/output.json

@@ -1,4 +1,5 @@
 {
+  "format_version": "0.1",
   "valid": true,
   "error_count": 0,
   "warning_count": 0,

command/validate.go

@@ -119,7 +119,14 @@ func (c *ValidateCommand) validate(dir string) tfdiags.Diagnostics {
 func (c *ValidateCommand) showResults(diags tfdiags.Diagnostics, jsonOutput bool) int {
 	switch {
 	case jsonOutput:
+		// 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"
+
 		type Output struct {
+			FormatVersion string `json:"format_version"`
+
 			// We include some summary information that is actually redundant
 			// with the detailed diagnostics, but avoids the need for callers
 			// to re-implement our logic for deciding these.
@@ -129,8 +136,10 @@ func (c *ValidateCommand) showResults(diags tfdiags.Diagnostics, jsonOutput bool
 			Diagnostics  []*viewsjson.Diagnostic `json:"diagnostics"`
 		}
 
-		var output Output
-		output.Valid = true // until proven otherwise
+		output := Output{
+			FormatVersion: FormatVersion,
+			Valid:         true, // until proven otherwise
+		}
 		configSources := c.configSources()
 		for _, diag := range diags {
 			output.Diagnostics = append(output.Diagnostics, viewsjson.NewDiagnostic(diag, configSources))

website/docs/cli/commands/validate.html.md

@@ -57,6 +57,12 @@ 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.
+
 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: