[← Two mechanisms](01-two-mechanisms.md) · [Index](../README.md) · [Registration →](03-registration.md)

# 2. Relaxed binding, measured

Everything here is generated by [`RelaxedBindingProbe`](../src/main/java/com/ankurm/configprops/web/RelaxedBindingProbe.java)
and re-checked against real processes by [`demo-env-binding.sh`](../scripts/demo-env-binding.sh).
Transcripts: [`01-relaxed-matrix.txt`](output/01-relaxed-matrix.txt),
[`02-env-var-binding.txt`](output/02-env-var-binding.txt).

## The canonical form

Every property has one canonical name: lower case, words separated by `-`, levels separated by
`.`. For `RelaxedProperties.apiKey` under prefix `demo.relaxed`, that is
`demo.relaxed.api-key`.

## What matches it

| Spelling | Source | Binder | `${}` plain Spring | `${}` in Spring Boot |
|---|---|---|---|---|
| `demo.relaxed.api-key` | file / `-D` | bound | bound | bound |
| `demo.relaxed.apiKey` | file / `-D` | bound | MISS | bound |
| `demo.relaxed.api_key` | file / `-D` | bound | MISS | bound |
| `demo.relaxed.APIKEY` | file / `-D` | bound | MISS | bound |
| `DEMO.RELAXED.API-KEY` | file / `-D` | bound | MISS | bound |
| `demo.relaxed.apikey` | file / `-D` | bound | MISS | bound |
| `demo.relaxed.api.key` | file / `-D` | **MISS** | MISS | **MISS** |
| `DEMO_RELAXED_API_KEY` | env var | bound | bound | bound |
| `DEMO_RELAXED_APIKEY` | env var | bound | MISS | bound |
| `demo_relaxed_api_key` | env var | bound | bound | bound |

## Reading it

**Dashes, underscores and case are noise.** `ConfigurationPropertyName` compares elements in a
"uniform" form with separators removed and case folded, so `api-key`, `apiKey`, `api_key` and
`apikey` are the same name.

**A dot is not noise.** `demo.relaxed.api.key` is four name elements; `demo.relaxed.api-key` is
three. Nothing relaxed will ever join them. This is the one spelling that genuinely fails, and
it is the one people write when they are guessing.

**`@Value` gets relaxed resolution too — but only inside Spring Boot.** The widely repeated
claim that `@Value` does not support relaxed binding is a statement about the Spring Framework.
Spring Boot calls `ConfigurationPropertySources.attach(environment)` while preparing every
environment, which inserts a property source that resolves placeholders through the binder's
name matching. Remove that call and the middle column is what you get.

That is worth knowing in both directions: you can rely on it in a Boot application, and you
cannot rely on it in a plain `ApplicationContext`, a standalone `Environment` or a test that
builds one by hand.

## Environment variables

Both `DEMO_RELAXED_API_KEY` and `DEMO_RELAXED_APIKEY` work. Prefer the first: `_` for every
separator, upper case throughout. It is the form the binder generates when it goes looking, so
it is the one that cannot depend on the reverse mapping.

A harness note that cost a wrong finding here: Spring Boot decides to apply environment-variable
name mapping by comparing the property source's *name* against
`StandardEnvironment.SYSTEM_ENVIRONMENT_PROPERTY_SOURCE_NAME`, not by checking its type. A
`SystemEnvironmentPropertySource` registered under any other name is mapped with the ordinary
rules. A test that builds one by hand and names it something descriptive will report that
underscore spellings do not bind, and will be wrong.