Spring Boot application.yml: Syntax, Profiles and Pitfalls

# ── Key-value pairs and nesting ──────────────────────────────────────
server:
  port: 8080                # integer — no quotes needed
  servlet:
    context-path: /api      # string — no quotes needed

# ── Strings, numbers, booleans ───────────────────────────────────────
app:
  name: MyApplication                # unquoted — fine for simple strings
  description: "My Spring Boot App: v2"  # quote values with ": " or " #" inside
  message: 'It''s working'           # single quotes — write '' for a literal '
  url: http://localhost:8080         # a colon NOT followed by a space is fine unquoted
  multiline: |                       # literal block — preserves newlines
    Line one
    Line two
  folded: >                          # folded block — newlines become spaces
    This is a very long
    description that wraps
  jwt:
    expiration: 86400                # int
    rate: 0.15                       # float
    enabled: true                    # boolean — always write true/false
    timeout: 30s                     # Duration, when bound to a Duration property
    max-upload: 10MB                 # DataSize, when bound to a DataSize property

  # ── Lists ──────────────────────────────────────────────────────────
  allowed-origins:                   # block list
    - https://myapp.com
    - https://admin.myapp.com
  allowed-methods: [GET, POST, PUT]  # inline list

  # ── Maps ───────────────────────────────────────────────────────────
  external-services:
    inventory: https://inventory:8082
    pricing: https://pricing:8083

# ── Placeholders: environment variables and defaults ─────────────────
spring:
  datasource:
    username: ${DB_USERNAME:app}                                  # with default
    password: ${DB_PASSWORD}                                      # required: startup fails if it is not defined
    url: ${DATABASE_URL:jdbc:mysql://localhost:3306/mydb}         # the default may contain colons
  profiles:
    active: dev                      # or a list: [dev, metrics]

# ── Logging levels are a map ─────────────────────────────────────────
logging:
  level:
    root: INFO
    com.example: DEBUG
    org.springframework.web: INFO

# Extra locations and imports
# application.yml
spring:
  config:
    import:
      - optional:file:./local-overrides.yml        # ignored if the file does not exist
      - optional:configtree:/run/secrets/          # one file per property, e.g. Docker/Kubernetes secrets

# Command line:
#   java -jar app.jar --spring.config.additional-location=file:/etc/myapp/
#   java -jar app.jar --spring.config.location=classpath:/,file:/etc/myapp/
#   java -jar app.jar --spring.profiles.active=prod --server.port=9000

# Environment variables (relaxed binding):
#   SPRING_PROFILES_ACTIVE=prod
#   SPRING_DATASOURCE_URL=jdbc:postgresql://db:5432/app
#   SPRING_DATASOURCE_HIKARI_MAXIMUM_POOL_SIZE=20
#   APP_ALLOWED_ORIGINS=https://a.com,https://b.com

# application.yml — complete Spring Boot 3.x configuration

server:
  port: 8080
  servlet:
    context-path: /api
  tomcat:
    threads:
      max: 200
      min-spare: 10
    connection-timeout: 5s
  compression:
    enabled: true
    mime-types: application/json,text/html
    min-response-size: 2KB
  shutdown: graceful

spring:
  application:
    name: myapp

  datasource:
    url: ${DATABASE_URL:jdbc:mysql://localhost:3306/mydb?useSSL=false&serverTimezone=UTC}
    username: ${DB_USERNAME:app}
    password: ${DB_PASSWORD}
    hikari:
      pool-name: myapp-pool
      maximum-pool-size: 10
      minimum-idle: 5
      idle-timeout: 300000
      connection-timeout: 20000
      max-lifetime: 1200000
      keepalive-time: 60000

  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: false
    open-in-view: false
    properties:
      hibernate:
        format_sql: true
        default_batch_fetch_size: 16
        jdbc:
          batch_size: 25

  flyway:
    enabled: true
    locations: classpath:db/migration
    validate-on-migrate: true

  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://auth.example.com

  data:
    redis:                      # Spring Boot 2.x: spring.redis
      host: ${REDIS_HOST:localhost}
      port: 6379
      timeout: 2s

  cache:
    type: redis

  jackson:
    serialization:
      write-dates-as-timestamps: false
    default-property-inclusion: non_null

  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 50MB

  lifecycle:
    timeout-per-shutdown-phase: 30s

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,loggers
  endpoint:
    health:
      show-details: when-authorized
      show-components: always
  info:
    env:
      enabled: true
    java:
      enabled: true

logging:
  level:
    root: INFO
    com.example: INFO
  pattern:
    console: "%d{HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n"   # quotes required: the value starts with %
  file:
    name: logs/myapp.log
  logback:
    rollingpolicy:
      max-file-size: 50MB
      max-history: 30

app:
  jwt:
    secret: ${JWT_SECRET}
    expiration: 86400
    issuer: https://myapp.com
  mail:
    from: noreply@myapp.com
  features:
    payments:
      enabled: true
    notifications:
      enabled: true

info:
  app:
    name: My Application
    version: 2.1.0

# ── APPROACH 1: Separate files ───────────────────────────────────────
# application.yml          — base config for all profiles
# application-dev.yml      — dev overrides (loaded when 'dev' is active)
# application-prod.yml     — prod overrides

# application-dev.yml:
spring:
  datasource:
    url: jdbc:h2:mem:devdb;MODE=MySQL
    username: sa
    password: ""
  h2:
    console:
      enabled: true
  jpa:
    show-sql: true
    hibernate:
      ddl-auto: create-drop

logging:
  level:
    com.example: DEBUG

# ── APPROACH 2: Multi-document YAML (single file) ─────────────────────
# Use --- to separate YAML documents within one file.
# Each document can target a profile with spring.config.activate.on-profile.

# application.yml:
---
# Document 1 — base config (no profile restriction, always applied):
server:
  port: 8080
spring:
  profiles:
    active: dev                          # default profile; override with SPRING_PROFILES_ACTIVE
    group:
      prod: [proddb, metrics]            # activating 'prod' also activates these
  jpa:
    show-sql: false
logging:
  level:
    root: INFO

---
# Document 2 — development overrides:
spring:
  config:
    activate:
      on-profile: dev                    # only applied when 'dev' is active
  datasource:
    url: jdbc:h2:mem:devdb
    username: sa
    password: ""
  jpa:
    show-sql: true
    hibernate:
      ddl-auto: create-drop
logging:
  level:
    com.example: DEBUG

---
# Document 3 — production settings:
spring:
  config:
    activate:
      on-profile: prod
  datasource:
    url: ${DATABASE_URL}
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
    hikari:
      maximum-pool-size: 20
logging:
  level:
    root: WARN
    com.example: INFO

---
# Document 4 — everything except production (profile expression):
spring:
  config:
    activate:
      on-profile: "!prod"
management:
  endpoints:
    web:
      exposure:
        include: "*"

# YAML lists — bound to Java List<String>:
app:
  allowed-origins:
    - https://myapp.com
    - https://admin.myapp.com
    - http://localhost:3000

  # Or inline list syntax:
  # allowed-origins: [https://myapp.com, https://admin.myapp.com]

  # YAML maps — bound to Java Map<String, String>:
  external-services:
    inventory: https://inventory:8082
    pricing: https://pricing:8083
    shipping: https://shipping:8084

  # Maps of typed sub-objects — bound to Map<String, ServiceConfig>:
  services:
    inventory:
      url: https://inventory:8082
      timeout: 5s
      retry-count: 3
    pricing:
      url: https://pricing:8083
      timeout: 3s
      retry-count: 2

  # List of objects — bound to List<NotificationChannel>:
  notification-channels:
    - type: email
      enabled: true
      priority: 1
    - type: sms
      enabled: true
      priority: 2
    - type: push
      enabled: false
      priority: 3

  # Map keys with special characters need bracket notation:
  route-roles:
    "[/api/users]": ADMIN
    "[/api/orders]": USER

@ConfigurationProperties(prefix = "app")
@Validated
public record AppProperties(
        @NotEmpty List<String> allowedOrigins,
        Map<String, String> externalServices,
        Map<String, ServiceConfig> services,
        List<NotificationChannel> notificationChannels,
        Map<String, String> routeRoles) {

    public record ServiceConfig(@NotBlank String url, Duration timeout, int retryCount) {}

    public record NotificationChannel(String type, boolean enabled, int priority) {}
}

@SpringBootApplication
@ConfigurationPropertiesScan          // registers AppProperties as a bean
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

@Service
public class InventoryClient {
    private final AppProperties.ServiceConfig config;

    public InventoryClient(AppProperties props) {
        this.config = props.services().get("inventory");   // url, timeout 5s, retryCount 3
    }
}

// pom.xml — IDE autocompletion for your own properties:
// <dependency>
//   <groupId>org.springframework.boot</groupId>
//   <artifactId>spring-boot-configuration-processor</artifactId>
//   <optional>true</optional>
// </dependency>

feature:
  enabled: yes            # boolean true (YAML 1.1) — write true
  country: NO             # boolean false!  — write "NO"
  switch: off             # boolean false
  version: 1.10           # float 1.1       — write "1.10"
  file-mode: 0755         # octal number 493 — write "0755"
  code: 007               # octal            — write "007"
  empty:                  # null (not an empty string)
  blank: ""               # empty string
  password: "p#ss word"   # quoted: '#' is safe
  pattern: "%d{HH:mm:ss}" # quoted: value starts with %
  wildcard: "*"           # quoted: '*' starts an alias in YAML
  note: "Build: 42"       # quoted: contains ': '
  url: http://localhost:8080   # fine: colon not followed by a space

# ── PITFALL 1: Tabs instead of spaces ────────────────────────────────
# WRONG — the next line starts with a TAB character; SnakeYAML throws a ScannerException:
server:
	port: 8080

# CORRECT — spaces only (2 spaces per level is Spring Boot convention):
server:
  port: 8080

# ── PITFALL 2: Wrong indentation level ───────────────────────────────
# WRONG — 'datasource' is at the top level, so the key becomes "datasource.url":
spring:
datasource:
  url: jdbc:mysql://...
# Symptom: "Failed to determine a suitable driver class" — Spring never saw your URL.

# CORRECT — key becomes "spring.datasource.url":
spring:
  datasource:
    url: jdbc:mysql://...

# ── PITFALL 3: Unquoted special characters ────────────────────────────
# WRONG — ": " inside a value:
app:
  description: My App: Version 2     # parse error: mapping values are not allowed here

# CORRECT:
app:
  description: "My App: Version 2"
  url: http://localhost:8080         # colon without a following space needs no quotes
  token: "abc #123"                  # a space followed by '#' starts a comment — quote it

# ── PITFALL 4: Booleans and other implicit types ─────────────────────
# yes/no/on/off are booleans in YAML 1.1 (see the type-surprises section):
feature:
  enabled: yes                       # true — write true / false explicitly

# ── PITFALL 5: Duplicate keys ────────────────────────────────────────
# WRONG — the same key twice at one level. Spring Boot's loader rejects duplicate
# keys and the application FAILS TO START with a "duplicate key" error:
spring:
  datasource:
    url: jdbc:h2:mem:devdb
  datasource:                        # duplicate key — startup error
    url: jdbc:mysql://...

# CORRECT — one 'datasource' key; use profiles to switch values.

# ── PITFALL 6: Multi-document separator ───────────────────────────────
# --- must be on its own line:
spring:
  application:
    name: myapp
---
spring:
  config:
    activate:
      on-profile: dev

# ── PITFALL 7: Profile rules in the wrong place ──────────────────────
# WRONG — activating profiles from inside a profile-specific document
# fails with InvalidConfigDataPropertyException:
---
spring:
  config:
    activate:
      on-profile: prod
  profiles:
    active: metrics                  # not allowed here

# ── PITFALL 8: Lists are replaced, not merged ────────────────────────
# application.yml:
app:
  allowed-origins:
    - https://myapp.com
    - https://admin.myapp.com
# application-dev.yml:
app:
  allowed-origins:
    - http://localhost:3000          # in 'dev' the list is ONLY localhost — the other two are gone

# ── PITFALL 9: Missing placeholder values ─────────────────────────────
spring:
  datasource:
    password: ${DB_PASSWORD}         # no default: startup fails with "Could not resolve placeholder"
    username: ${DB_USERNAME:app}     # with default: safe for local development

# ── PITFALL 10: @PropertySource and YAML ──────────────────────────────
# @PropertySource("classpath:extra.yml") does NOT parse YAML.
# Use spring.config.import: optional:classpath:extra.yml instead.

# ── FLAT PROPERTIES (repetitive prefixes): ───────────────────────────

spring.datasource.url=jdbc:mysql://localhost:3306/mydb
spring.datasource.username=root
spring.datasource.password=secret
spring.datasource.hikari.maximum-pool-size=10
spring.datasource.hikari.minimum-idle=5
spring.datasource.hikari.connection-timeout=20000
spring.jpa.hibernate.ddl-auto=validate
spring.jpa.show-sql=false
spring.jpa.open-in-view=false
spring.jpa.properties.hibernate.format_sql=true
spring.jpa.properties.hibernate.default_batch_fetch_size=16

# ── EQUIVALENT YAML (hierarchical — no prefix repetition): ────────────

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mydb
    username: root
    password: secret
    hikari:
      maximum-pool-size: 10
      minimum-idle: 5
      connection-timeout: 20000
  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: false
    open-in-view: false
    properties:
      hibernate:
        format_sql: true
        default_batch_fetch_size: 16

# For deep nesting (JPA, Hibernate, Actuator): YAML wins clearly
# For shallow config (single-level properties): .properties is simpler

# ── CHOOSE PROPERTIES WHEN: ───────────────────────────────────────────
# - Team is more comfortable with properties format
# - Configuration is mostly shallow (few nested levels)
# - You frequently append single values
# - You want to avoid YAML indentation errors
# - You need @PropertySource or @TestPropertySource files

# ── CHOOSE YAML WHEN: ─────────────────────────────────────────────────
# - Configuration has deep nesting (datasource, JPA, security)
# - You use multi-document profiles (--- separators)
# - You need lists or maps in configuration
# - Team prefers the structured format

# ── MIXING IS POSSIBLE BUT NOT RECOMMENDED: ───────────────────────────
# Spring Boot reads both application.properties AND application.yml.
# If both define the same key in the same location, .properties wins.
# Stick to one format per project for consistency.

# application.yml — expose the endpoints temporarily (do NOT expose env publicly in production)
management:
  endpoints:
    web:
      exposure:
        include: health,info,env,configprops

# Then:
#   curl http://localhost:8080/actuator/env/spring.datasource.url
#   {
#     "property": { "source": "applicationConfig: [classpath:/application-dev.yml]", "value": "jdbc:h2:mem:devdb" },
#     "propertySources": [ ... every source that defines the key ... ]
#   }
#
#   curl http://localhost:8080/actuator/configprops      # all @ConfigurationProperties beans and their bound values

# See which config files were loaded:
#   java -jar app.jar --debug
#   java -jar app.jar --logging.level.org.springframework.boot.context.config=TRACE