Configuration in Full: Properties, YAML, Binding and Profiles

No Spring Boot magic in this article — just a plain @Component and a handful of annotations — so that you can answer one question confidently: where does a configuration value come from, and why did my file edit do nothing?

When a Spring Boot app starts it reads configuration from many places at once: the application.yml inside the jar, a second copy you dropped next to the jar, environment variables on the server, -D flags, and finally --server.port=9090 typed at the end of the command line. When the same key (say server.port) appears in several of them, Spring Boot does not complain and does not "merge" anything — it asks a fixed list of sources in order, and the first one that answers wins. This article covers four things: where config can live, which layer shadows which, how to get a value into a Java field (binding), and how Profiles let one codebase carry a different value set per environment.

After this article you should be able to answer three questions:

• I edited the application.yml sitting next to the jar — why does the service still come up on the old port? Which layer shadows it?
• @Value("${bee.max-size}") and @ConfigurationProperties(prefix = "bee") — does the same environment variable work for both? Why do the answers differ?
• If spring.profiles.active is off by one letter in production, what happens, and how do I prove for myself that the profile really took effect?

Spring Boot lets you carry configuration in three file types, all of which are ultimately parsed into the same PropertySource. Choosing among them is mostly a team habit, but the differences are real:

The same config in two styles:

This is the table most worth internalizing. Spring Boot gathers configuration from many places, and when the same key appears in several, the highest-priority layer wins (note: not "the later overrides the earlier" but "the first match by priority is taken"):

• Command line > environment variables > external files > packaged files > defaults is the memory spine
• "External" means the directory holding the jar or a config/ beneath it, used to override config without repackaging
• Profile-specific files (application-prod.yml) outrank generic files (application.yml), and both come after the packaged/external split

Fourteen rows is a lot to hold in your head, but a real investigation only ever walks three or four of them. Here is the same chain as boxes you can click through; box ③ carries the only idea in this section worth memorising: it is not merging, it is being asked first.

Both read config into Java, but they differ deeply:

"Relaxed binding" means a property's written form can vary while still binding to the same Java field. This reconciles three naming habits — kebab-case in yml, underscores in constants, camelCase in fields:

The comparison that diagram is making: @Value("${sms.template-id}") performs a literal exact match — write sms.templateId and it refuses; whereas @ConfigurationProperties(prefix = "sms") compares normalized names, stripping separators and lower-casing both the property name and the field name, so all five forms below land on the same field:

The real power of @ConfigurationProperties is complex types, which @Value can hardly do:

When config is wrong, the ideal is to fail fast at startup and name the offending field. That takes a trio: @Validated + validation annotations + a validation implementation:

When config is invalid, startup fails with a message pinpointing the field:

Once the trio is in place, generating the properties class beats copying one — and pay particular attention to the last option: the same class can be admitted three different ways, and each emits different code.

Profiles are Spring's official answer to multiple environments: one codebase that loads different config and wires different beans per active profile.

First, the @Profile annotation — essentially a preset of conditional wiring:

A far more common approach uses profile-specific config files, folding the differences into files instead of code:

spring.profiles.active has four common ways to activate:

Profile expressions also support logic:

"Activate prod" fires two things at once: one file joins the configuration chain, and a batch of bean conditions turn green. This animation runs both lines together — look at frame 6, because @Profile and the profile-specific file are driven by one and the same switch:

Which lines actually belong in a multi-environment setup is faster to generate than to copy. Tick "per-env blocks" alone first and watch how --- pairs with spring.config.activate.on-profile; then add datasource and logging and compare with the application-dev.yml / application-prod.yml split above; finally add the server block and see why server.port so often loses to an environment variable in production (lab prop order in Section 11 replays that chain).

Production database passwords and keys must never sit in plaintext in the artifact. There are two mainstream routes:

• Jasypt in one line: add jasypt-spring-boot-starter, write ENC(ciphertext) in config, and decrypt at startup with a key. Fits "the ciphertext must live in the config file" situations
• Environment-variable injection (preferred): write only a placeholder ${DB_PASSWORD} in config and let the platform (K8s Secret, CI variable) inject the real value — the password never appears in the repository at all

Writing ${DB_PASSWORD} like that is placeholder resolution: the container substitutes the real value during the binding phase, and the substituted result then goes through the precedence chain again — which means the name DB_PASSWORD itself competes on that chain.

Three rules govern resolution, and knowing them means never being stumped by "why can't my yml placeholder see the environment variable":

• The name is looked up on the precedence chain first. If DB_PASSWORD happens to be defined in some application.yml as well, that value wins — not the OS environment variable
• A colon supplies a fallback. ${DB_PASSWORD:guest} yields guest when nothing is found and never fails; ${DB_PASSWORD} throws instead
• Not found means an exception that names the key. The full text is org.springframework.beans.factory.BeanCreationException: Could not resolve placeholder 'DB_PASSWORD' in value "${DB_PASSWORD}" — searching the first half finds it

"Before binding" is what gives these failures their particular shape, so unfold it as a single-step run: six lines of startup on the left, variables and call stack refreshing on the right. Step through and stop on beat ④ — that beat asks for a property name, not for an operating-system variable name:

Beat ④ above is the single most frequent production-only startup failure in this chapter. Here is the real stack — do not read the analysis, just click the frame you think is guilty:

Everything above is "read once at startup, then fixed". In Spring Cloud there is sometimes a need to update config without a restart — that is where @RefreshScope comes in: it wraps the bean in a proxy, destroys and rebuilds it when config changes, so new values are read.

Configuration errors share one temperament: the message never names the actual cause. mapping values are not allowed here never says "tab", Could not resolve placeholder never says "the names do not match". So rather than memorising, click once — exact wording on the left, what it is really complaining about on the right:

This chapter has nine kernel labs, and one pass in this order is enough: ① first see how "config read or not" changes the bean, then ②③④⑤ press precedence, relaxed binding, placeholders and profiles individually, ⑥ then climb up to the startup spine to find where configuration is already in place, and finally ⑦⑧⑨ reconnect it to the three underlying mechanisms — conditional wiring, how beans get admitted, and auto-configuration.

The first demo turns "config has been read" into a switch. Toggle it and watch the DataSource pool parameters (max connections, timeout) change with the config:

The second lab is the direct cure for "I edited the config and nothing happened": write the same server.port into the command line, an environment variable and a packaged file, then watch the precedence chain ask each one in turn.

The third lab turns the Section 4 table into something clickable: switch the written form of a property and see whether it still binds to the templateId field.

The fourth lab shows placeholder resolution in order, including the fallback and the failure case.

The fifth lab plays out Section 7's "one letter off" trap: the profile name has to match in two places, the activation setting and the file name. Miss either and the app falls back to the generic config — and still starts happily.

The sixth lab asks the question that comes earlier: at which step of startup is configuration actually read? The answer is before the container refreshes, and that is why Section 8's "resolution before binding" and Section 13's "the value you see in @PostConstruct is already final" are both the same fact:

The seventh lab puts @Profile back where it belongs — in conditional wiring. A configuration class that loses does not error, it just leaves a verdict line in the report, exactly like article 19:

The eighth lab untangles the two "no such bean" messages of this chapter: a properties class that declared itself but was never admitted, versus one that is not even in scan range. The wording is nearly identical:

The ninth lab answers "why does @Value work with nothing configured at all": the bean that resolves placeholders, PropertySourcesPlaceholderConfigurer, is itself the product of one auto-configuration, and here is which questions it had to pass:

Enough buttons — type the commands yourself. This console talks to the same in-browser kernel, and every reply is computed there:

Earlier sections covered @Value and @ConfigurationProperties, but engineering actually has four roads to a value. The trade-off sits on two axes: type safety (do you get an int/Duration or a string you convert yourself) and granularity (one key at a time, or a whole prefix at once).

The third row is the one beginners never discover, because nobody shows them the code: