Properties vs YAML

Externalized configuration allows the same compiled Spring Boot JAR to run unmodified across development workstations, CI test pipelines, staging clusters, and production data centers. Spring Boot builds a unified PropertySources hierarchy from over 15 distinct sources, evaluating them in a strict top-down precedence order where higher-priority sources override lower ones.

1. 011. Command-line arguments (--server.port=9090 has the highest standard priority)
2. 022. Java System properties (-Dserver.port=9090) passed to the JVM
3. 033. OS Environment variables (SERVER_PORT=9090) standard for containers and Kubernetes
4. 044. Kubernetes ConfigTree files (spring.config.import=configtree:/etc/config/)
5. 055. Profile-specific application-{profile}.yml outside the packaged JAR
6. 066. Profile-specific application-{profile}.yml inside the packaged JAR
7. 077. Application default application.yml outside the packaged JAR
8. 088. Application default application.yml inside the packaged JAR
9. 099. Default properties defined on @PropertySource or SpringApplication.setDefaultProperties()

Spring Boot natively supports both flat .properties files and hierarchical .yml (or .yaml) files. While both feed the identical Environment abstraction, their syntax rules and capabilities differ dramatically.

1
2
3
4
5
6
7
8
9
10
11
12

server:
  port: 8080
  shutdown: graceful

app:
  security:
    cors:
      allowed-origins:
        - "https://app.example.com"
        - "https://admin.example.com"
    feature-flags:
      enable-beta-checkout: false # Note: Avoid raw 'no' or 'off' which YAML parsers might coerce

Spring Boot provides relaxed binding: property names can be written in kebab-case, camelCase, snake_case, or uppercase screaming snake, and Boot maps them to the same destination. However, operating system environment variables have strict naming constraints (POSIX shells allow only alphanumeric characters and underscores).

The Spring Boot team strongly recommends writing all property keys in canonical kebab-case (e.g. app.payment-service.timeout-ms) inside application.yml and using uppercase screaming snake in environment variables (APP_PAYMENTSERVICE_TIMEOUTMS).

A frequent operational incident occurs when an engineer attempts to override a list property via environment variables. By default, environment variables do not append to existing lists; they replace entries by index or fail to match if array indexing syntax is not honored.

1
2
3
4

app:
  admin-emails:
    - "alice@example.com"
    - "bob@example.com"

1
2
3

# Fails to replace the entire list as expected:
export APP_ADMIN_EMAILS="charlie@example.com"
# Result: Charlie does not append; depending on binder, it may crash or only bind to index 0 leaving index 1 intact!