From dc7f2b731449478b7b23ecbe3071000376d05924 Mon Sep 17 00:00:00 2001 From: Martin Atkins Date: Fri, 12 Mar 2021 08:42:27 -0800 Subject: [PATCH] website: docs for the terraform validate JSON output --- website/docs/cli/commands/validate.html.md | 109 +++++++++++++++++++++ 1 file changed, 109 insertions(+) diff --git a/website/docs/cli/commands/validate.html.md b/website/docs/cli/commands/validate.html.md index 344b094be..62bcb7e9f 100644 --- a/website/docs/cli/commands/validate.html.md +++ b/website/docs/cli/commands/validate.html.md @@ -44,3 +44,112 @@ This command accepts the following options: color. - `-no-color` - If specified, output won't contain any color. + +## JSON Output Format + +When you use the `-json` option, Terraform will produce validation results +in JSON format to allow using the validation result for tool integrations, such +as highlighting errors in a text editor. + +As with all JSON output options, it's possible that Terraform will encounter +an error prior to beginning the validation task that will thus not be subject +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. + +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: + +* `valid` (boolean): Summarizes the overall validation result, by indicating + `true` if Terraform considers the current configuration to be valid or + `false` if it detected any errors. + +* `error_count` (number): A zero or positive whole number giving the count + of errors Terraform detected. If `valid` is `false` then `error_count` will + always be zero, because it is the presence of errors that indicates that + a configuration is invalid. + +* `warning_count` (number): A zero or positive whole number giving the count + of warnings Terraform detected. Warnings do not cause Terraform to consider + a configuration to be invalid, but they do indicate potential caveats that + a user should consider and possibly resolve. + +* `diagnostics` (array of objects): A JSON array of nested objects that each + describe an error or warning from Terraform. + +The nested objects in `diagnostics` have the following properties: + +* `severity` (string): A string keyword, currently either `"error"` or + `"warning"`, indicating the diagnostic severity. + + The presence of errors causes Terraform to consider a configuration to be + invalid, while warnings are just advice or caveats to the user which do not + block working with the configuration. Later versions of Terraform may + introduce new severity keywords, so consumers should be prepared to accept + and ignore severity values they don't understand. + +* `summary` (string): A short description of the nature of the problem that + the diagnostic is reporting. + + In Terraform's usual human-oriented diagnostic messages, the summary serves + as a sort of "heading" for the diagnostic, printed after the "Error:" or + "Warning:" indicator. + + Summaries are typically short, single sentences, but can sometimes be longer + as a result of returning errors from subsystems that are not designed to + return full diagnostics, where the entire error message therefore becomes the + summary. In those cases, the summary might include newline characters which + a renderer should honor when presenting the message visually to a user. + +* `detail` (string): An optional additional message giving more detail about + the problem. + + In Terraform's usual human-oriented diagnostic messages, the detail provides + the paragraphs of text that appear after the heading and the source location + reference. + + Detail messages are often multiple paragraphs and possibly interspersed with + non-paragraph lines, so tools which aim to present detail messages to the + user should distinguish between lines without leading spaces, treating them + as paragraphs, and lines with leading spaces, treating them as preformatted + text. Renderers should then soft-wrap the paragraphs to fit the width of the + rendering container, but leave the preformatted lines unwrapped. + + Some Terraform detail messages currently contain an approximation of bullet + lists using ASCII characters to mark the bullets. This is not currently a + contractural formatting convention and so renderers should avoid depending on + it and should instead treat those lines as either paragraphs or preformatted + text per the rules above. A future version of this format may define some + additional rules for processing other text conventions, but will do so within + the bounds of the rules above to achieve backward-compatibility. + +* `range` (object): An optional object describing a portion of the configuration + source code that the diagnostic message relates to. For errors, this will + typically indicate the bounds of the specific block header, attribute, or + expression which was detected as invalid. + + A source range is an object with a property `filename` which gives the + filename as a relative path from the current working directory, and then + two properties `start` and `end` which are both themselves objects + describing source positions, as described below. + + Not all diagnostic messages are connected with specific portions of the + configuration, so `range` will be omitted or `null` for diagnostic messages + where it isn't relevant. + +A source position object, as used in the `range` property of a diagnostic +object, has the following properties: + +* `byte` (number): A zero-based byte offset into the indicated file. + +* `line` (number): A one-based line count for the line containing the relevant + position in the indicated file. + +* `column` (number): A one-based count of _Unicode characters_ from the start + of the line indicated in `line`. + +A `start` position is inclusive while an `end` position is exclusive. The +exact positions used for particular error messages are intended for human +interpretation only and subject to change in future versions of Terraform due +either to improvements to the error reporting or changes in implementation +details of the language parser/evaluator.