Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 66 ยท Auto-Configuration and Configuration

Properties, YAML and Externalized Config

How Spring Boot reads application.properties and application.yml, which property source wins, how environment variables and relaxed binding work, and how placeholders resolve.

The same jar should run on your laptop, in a test pipeline and in production without being rebuilt. Only the settings change: a database URL, a port, a feature flag. Spring Boot calls this externalized configuration. Your code asks the Environment for a value, and Boot assembles that value from many places in a fixed order of priority.

Once you know the order, configuration stops being mysterious. When a value is "wrong", you can find out which source supplied it. This lesson covers the file formats, the list of sources from strongest to weakest, how environment variables map onto property names, and how ${...} placeholders work. Real Spring Boot cannot run here, so configuration files are read-only, and two plain-Java stand-ins reproduce the ordering and placeholder logic.

properties and YAML

Boot reads application.properties or application.yml (also .yaml) from the classpath and from a few locations next to the jar. The two formats express the same keys.

PROPERTIES
server.port=8081
app.greeting=Hello
app.mail.host=smtp.example.com
app.mail.port=587
YAML
server:
  port: 8081
app:
  greeting: Hello
  mail:
    host: smtp.example.com
    port: 587

YAML nests keys, so repeated prefixes disappear and lists are easy. Both produce flat keys like app.mail.host internally. Lists use dash syntax in YAML and indexes in properties:

YAML
app:
  allowed-origins:
    - https://example.com
    - https://admin.example.com
PROPERTIES
app.allowed-origins[0]=https://example.com
app.allowed-origins[1]=https://admin.example.com

A YAML file can hold several documents separated by ---. Each document can be limited to a profile, which the profiles lesson covers in full.

YAML turns some bare words into booleans or numbers. Values like on, off, yes and no can become true or false, and a country code NO for Norway may surprise you. Quote any value where the type matters: country: "NO". Also keep tabs out of YAML; it only accepts spaces for indentation.

If both application.properties and application.yml exist in the same location, the properties file wins. Most projects pick one format and keep to it.

Where files are searched

Boot checks these locations, and later ones override earlier ones:

  1. classpath:/ (inside the jar, from src/main/resources)
  2. classpath:/config/
  3. the current working directory ./
  4. ./config/ and its direct subfolders

So a file named application.properties placed next to the jar overrides the one packed inside it. This is how operations teams change settings on a server without touching the artifact. You can also point at another file explicitly with --spring.config.location= or add one with --spring.config.additional-location=.

The order of property sources

The key rule is simple: the first source in the list that defines a key wins. This is the short version, from strongest to weakest:

Strongest sources

Test properties @SpringBootTest(properties=...) overrides all.
Command line --server.port=9000 on java -jar.
JSON in env SPRING_APPLICATION_JSON as one blob.
JVM properties -Dserver.port=9000.
1 / 3

Two consequences matter every day. First, environment variables override files, which is why containers configure apps with variables and no file changes. Second, command-line arguments override environment variables, which makes a quick --server.port=9001 the right tool for a one-off test.

Within the file layers, a profile-specific file such as application-prod.yml beats the plain application.yml at the same location. The TryIt below implements the "first source wins" rule with a list of sources in priority order, including command-line parsing and the mapping between SERVER_PORT and server.port. It also reports which sources were shadowed, which is the information you want when debugging.

Java Which source wins?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

What is real: the first-match-wins idea, the fact that APP_GREETING and app.greeting name the same property, and the priority between command line, environment and files. What is the stand-in: Boot builds PropertySource objects with precise origin tracking, supports many more locations and types, and uses an exact (not lowercase-flattened) conversion for names.

Environment variables and relaxed binding

Operating systems restrict environment variable names: no dots, usually uppercase with underscores. Boot's relaxed binding bridges that gap. For a property app.mail.host these all refer to the same setting:

Where Form
.properties/.yml (recommended) app.mail.host, kebab-case, lowercase
Environment variable APP_MAIL_HOST
System property -Dapp.mail.host=...

The rule for environment variables: replace dots with underscores, replace dashes by removing them (or underscores), and use uppercase. So app.max-connections becomes APP_MAXCONNECTIONS or APP_MAX_CONNECTIONS. For list items, use the index inside underscores: APP_ALLOWEDORIGINS_0. Always write kebab-case (max-connections) in files, because that form works for every binding style and is what the metadata and documentation use.

One difference matters: relaxed binding applies to properties bound into typed objects (see Type-Safe @ConfigurationProperties). A plain @Value("${app.max-connections}") is stricter, so prefer typed binding for anything beyond one or two values.

Placeholders

Any value may reference other properties with ${name}, and may give a fallback after a colon:

PROPERTIES
app.name=Shop
app.title=Welcome to ${app.name}
app.timeout=${APP_TIMEOUT:30s}
app.data-dir=${user.home}/${app.name}/data

Placeholders resolve against the whole environment, so they can read environment variables and JVM properties like user.home. A missing key without a default raises an error at startup, which is usually what you want: fail fast instead of running with a half-configured app. A reference loop (a=${b}, b=${a}) is also detected and rejected.

The second TryIt rebuilds placeholder expansion: nested references, defaults and loop detection.

Java Placeholder expansion

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The real PropertyPlaceholderHelper also supports escaping and runs on the combined Environment; this stand-in keeps the three behaviors you will see in practice: nesting, fallback values and fail-fast errors.

Reading values in code

Spring gives you three ways to read a setting. Prefer them in this order:

Java
// 1. A typed object (best for groups of related settings)
@ConfigurationProperties(prefix = "app.mail")
public record MailProperties(String host, int port) {}

// 2. A single value with @Value (fine for one-off settings)
@Value("${app.greeting:Hello}")
private String greeting;

// 3. The Environment (when the key is computed at runtime)
String port = environment.getProperty("app.mail.port", "25");

Practical rules

  • Keep defaults in application.yml, safe for development, and override per environment with variables.
  • Never commit secrets. Pass them as environment variables, mounted files or a secret manager; see Profiles and Environment-Specific Config.
  • Use kebab-case keys in files (max-connections), and one prefix per feature.
  • Inspect the result: the Actuator env and configprops endpoints show every source and the winning value (secured, because they expose settings).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. The jar contains server.port=8080, and the container sets the environment variable SERVER_PORT=9090. Which port is used?

    Environment variables rank above files, and relaxed binding maps SERVER_PORT to server.port, so the variable wins.
  2. 2. Which value is used for app.timeout in app.timeout=${APP_TIMEOUT:30s} when no APP_TIMEOUT is set?

    The text after the colon is the fallback used when the key is missing.
  3. 3. What happens with ${app.secret} when nothing defines app.secret and there is no default?

    An unresolvable placeholder fails fast instead of letting the application run half-configured.
  4. 4. Both application.properties and application.yml exist in the same folder and define app.mode. Which wins?

    At the same location the properties file takes precedence over the YAML file.

Summary

  • Boot reads application.properties or .yml from the classpath and from files next to the jar; files outside the jar win.
  • The first source that defines a key wins: command line, then JVM properties, environment variables, files (profile files before plain ones), and finally defaults.
  • Relaxed binding maps APP_MAIL_HOST to app.mail.host; write kebab-case keys in files.
  • ${key:fallback} placeholders resolve against the whole environment and fail fast when a key is missing.
  • Prefer typed binding over scattered @Value annotations.

Next: Type-Safe @ConfigurationProperties.