Document that property placeholders should use the canonical property name form

[larrywest42]

This is a request to improve the documentation by mentioning that "placeholders" (the property names) must always be spelt either:

• in the uniform format (kabob-case, kabab-case, kebab-case) as documented in Spring Boot Relaxed Binding 2.0, or
• in the original format (camelCase, snake_case) in which the property was defined.

(I haven't considered environment variables here.)

This may seem obvious, but I could not find it documented anywhere; not

• at the above document,
• nor in "Property Placeholders" in §7.2.3 of the Spring Boot Reference Documentation,
• nor in Spring Boot Configuration Binding
• nor in the source for PropertySourcesPlaceholdersResolver.

The closest I could find is in the Spring Boot Relaxed Binding 2.0 document, which only says:

We recommend that properties are stored [...] in lowercase kabab format.

I think something stronger and/or more detailed is called for.

☞ If it would help, I'd gladly put in a PR with the additional paragraph or two, if you'll point me to the appropriate documentation (source).

Example

In case anyone doubts this behavior, I'm attaching a trivial demonstration built from start.spring.io with Spring Boot 2.7 & Java 17, but I am pretty sure this behavior dates back to 2.0, at least.

The properties in the demo:

value.camelCase=v.cC
value.uniform-format=v.u-f

second.cc-via-cc=${value.camelCase}
second.uf-via-uf=${value.uniform-format}
second.cc-via-uf=${value.camel-case}
second.uf-via-cc=${value.uniformFormat}

# The first three work as expected. The fourth, referencing a property defined
# in uniform format by using camelCase name, is not resolved.

resolving-placeholders-demo.zip

[philwebb]

Thanks for the suggestion @larrywest42. I've added something similar to note we had in the "@ConfigurationProperties vs. @Value" section.