From 3345c85b23ea1abcbceb1eb42cc6d3e78e1b97b2 Mon Sep 17 00:00:00 2001
From: Adrien Delorme <adrien.delorme@icloud.com>
Date: Mon, 6 Apr 2020 16:14:27 +0200
Subject: [PATCH] Document Block-type-specific Exceptions in HCL2 json

---
 .../from-1.5/syntax-json.html.md              | 34 ++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/website/source/docs/configuration/from-1.5/syntax-json.html.md b/website/source/docs/configuration/from-1.5/syntax-json.html.md
index a264b5f12..89e3dffb5 100644
--- a/website/source/docs/configuration/from-1.5/syntax-json.html.md
+++ b/website/source/docs/configuration/from-1.5/syntax-json.html.md
@@ -86,7 +86,9 @@ source "amazon-ebs" "example" {
 ```
 
 Within each top-level block type the rules for mapping to JSON are slightly
-different (see [Block-type-specific Exceptions][inpage-exceptions] below), but the following general rules apply in most cases:
+different (see the [block-type-specific
+exceptions](#block-type-specific-exceptions) below), but the following general
+rules apply in most cases:
 
 * The JSON object representing the block body contains properties that
   correspond either to argument names or to nested block type names.
@@ -274,3 +276,33 @@ configuration file. This can be useful to note which program created the file.
   "//": "This file is generated by generate-outputs.py. DO NOT HAND-EDIT!",
 }
 ```
+
+## Block-type-specific Exceptions
+
+[inpage-block]: #block-type-specific-exceptions
+
+Certain arguments within specific block types are processed in a special way,
+and so their mapping to the JSON syntax does not follow the general rules
+described above. The following sub-sections describe the special mapping rules
+that apply to each top-level block type.
+
+### `variable` blocks
+
+All arguments inside `variable` blocks have non-standard mappings to JSON:
+
+* `type`: a string containing a type expression, like `"string"` or `"list(string)"`.
+* `default`: a literal JSON value that can be converted to the given type.
+  Strings within this value are taken literally and _not_ interpreted as
+  string templates.
+* `description`: a literal JSON string, _not_ interpreted as a template.
+
+```json
+{
+  "variable": {
+    "example": {
+      "type": "string",
+      "default": "hello"
+    }
+  }
+}
+```