application.yml – The Complete Spring Boot Configuration Playbook for 2025

Author: Technical Editorial Team  |  Last Updated: July 2025  |  Read Time: 18 min

Key Takeaways

• application.yml is the default configuration file for Spring Boot apps; it replaces the older properties file and uses indentation-based YAML syntax.
• Profile-specific YAML files (e.g., application-dev.yml) let you override settings per environment without changing code.
• Spring Boot merges configurations from multiple sources — application.yml, OS environment variables, command-line args, and externalized config — following a strict precedence order.
• Bad YAML indentation is the #1 cause of Spring Boot startup failures; always validate syntax before deployment.
• Externalize secrets using environment variables, Vault, or Jasypt encryption instead of hard-coding credentials in application.yml.

What Is application.yml?

application.yml is a hierarchical YAML configuration file placed in src/main/resources/ of every Spring Boot project. It tells Spring Boot how to configure data sources, server ports, logging levels, feature toggles, and any custom property your application needs.

When Spring Boot starts, it automatically loads application.yml from the classpath and binds nested keys to Java fields via the @ConfigurationProperties annotation or the ${property.name} placeholder syntax.

YAML vs. Properties Files – Which Should You Use?

Standard application.yml Structure

Every production-grade application.yml follows a predictable layout. Below is the canonical structure you should adopt.

spring:
  application:
    name: my-service
  datasource:
    url: jdbc:postgresql://localhost:5432/mydb
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
    driver-class-name: org.postgresql.Driver
  jpa:
    hibernate:
      ddl-auto: update
    properties:
      hibernate:
        dialect: org.hibernate.dialect.PostgreSQLDialect

server:
  port: ${SERVER_PORT:8080}
  servlet:
    context-path: /api

logging:
  level:
    root: INFO
    com.example.myapp: DEBUG
    org.springframework.web: WARN

myapp:
  feature-toggles:
    new-checkout: true
    beta-api-enabled: false
  allowed-origins:
    - https://example.com
    - https://admin.example.com

Step-by-Step: Setting Up application.yml in a Spring Boot Project

• Step 1 – Create src/main/resources/application.yml in your Spring Boot project root.
• Step 2 – Define spring.application.name at the top; every service should declare its own name for service discovery.
• Step 3 – Configure the data source, JPA / Hibernate, and connection pool settings under spring.datasource and spring.jpa.
• Step 4 – Set server.port and server.servlet.context-path; use port 0 for random assignment in containerized environments.
• Step 5 – Add sensitive values as environment-variable placeholders: ${SECRET_VAR:default_value}.
• Step 6 – Create custom namespace blocks (e.g., myapp:) for application-specific configuration that maps to @ConfigurationProperties beans.
• Step 7 – Validate the file with a YAML linter before committing to version control.

Environment-Specific Profiles

Spring Boot's profile system is the most powerful feature of application.yml. Profiles let you maintain one codebase while switching configurations per environment.

Profile Naming Convention

Activating a Profile

• Command line: java -jar app.jar --spring.profiles.active=prod
• Environment variable: SPRING_PROFILES_ACTIVE=prod
• application.yml:

  spring:
    profiles:
      active: ${SPRING_PROFILES_ACTIVE:dev}

spring:
  config:
    activate:
      on-profile: [dev, docker]