Document when and how to use brackets when binding to maps

mbhave · mbhave · commit 660d284f4555 · 2018-07-19T16:31:59.000-07:00
Closes spring-projectsgh-13506
diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc
@@ -1102,6 +1102,24 @@ property name
 TIP: We recommend that, when possible, properties are stored in lower-case kebab format,
 such as `my.property-name=acme`.
 
+When binding to `Map` properties, if the `key` contains anything other than lowercase
+alpha-numeric characters or `-`, you need to use the bracket notation so that the original
+value is preserved. If the key is not surrounded by `[]`, any characters that are not alpha-numeric
+or `-` are removed. For example, consider binding the following properties to a `Map`:
+
+[source,yaml,indent=0]
+----
+	acme:
+	  map:
+	    "[/key1]": value1
+	    "[/key2]": value2
+	    /key3: value3
+
+----
+
+The properties above will bind to a `Map` with `/key1`, `/key2` and `key3` as the keys in the map.
+
+
 [[boot-features-external-config-complex-type-merge]]
 ==== Merging Complex Types
 When lists are configured in more than one place, overriding works by replacing the entire
