YAML vs Properties Files in Spring Boot: Best Practices & Use Cases

Configuration is the silent killer of Spring Boot applications. I've seen production incidents caused by a missing space in a YAML file or a misplaced dot in a .properties file. Both formats are first-class citizens in Spring Boot, but they have fundamentally different strengths and weaknesses. In this article, we'll dive into the technical differences, best practices, and real-world gotchas. We'll also look at how Spring Boot 3.1+ handles both formats, and why you should care about the order of profile-specific files. By the end, you'll know exactly which format to choose for your next microservice or monolithic beast.

Introduction to Configuration Files in Spring Boot

Spring Boot has supported both .properties and YAML (.yml or .yaml) files since its early days. The application.properties file is the default, but you can switch to application.yml by simply renaming it. Spring Boot loads configuration from multiple sources in a specific order: command-line arguments, JNDI attributes, system properties, environment variables, and finally the application-{profile}.{ext} files. Understanding this order is critical for debugging production issues. For example, if you set server.port in an environment variable, it will override the value in your file. Both formats support profile-specific files like application-dev.properties or application-prod.yml. The key difference is how they handle structure: .properties uses a flat key-value approach, while YAML uses indentation to represent nested objects and lists. In Spring Boot 3.1, the spring.config.import property allows you to import additional config files, which works with both formats.

# Simple key-value pairs
server.port=8080
spring.datasource.url=jdbc:mysql://localhost:3306/mydb
spring.datasource.username=root
spring.datasource.password=secret
spring.jpa.hibernate.ddl-auto=update

# Lists (using array notation)
myapp.servers[0]=server1.example.com
myapp.servers[1]=server2.example.com

What the Official Docs Won't Tell You

The official Spring Boot documentation is excellent, but it glosses over some real-world pain points. First, YAML's indentation sensitivity is a double-edged sword: it makes configuration more readable, but a single wrong space can break your entire app silently. Second, Spring Boot 2.x and 3.x treat YAML differently when it comes to profile-specific documents. In a single YAML file, you can use --- to separate multiple documents, each with its own spring.profiles property. This is convenient but can lead to confusion when you have dozens of profiles. Third, the @ConfigurationProperties binding works flawlessly with both formats, but YAML's nested structure maps more naturally to Java POJOs. However, if you use YAML with @Value, you must be careful with the @Value syntax (e.g., ${myapp.server.url}) because YAML doesn't use dots for nesting. Fourth, Spring Boot 3.1 introduced the spring.config.import feature, which allows you to import other config files. This works with both formats, but YAML imports can be tricky because the imported file must also be valid YAML. Finally, the official docs don't emphasize enough that you should never mix both formats in the same project unless you're migrating. The spring.config.additional-location property can lead to unpredictable behavior if both formats are present.

server:
  port: 8080
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mydb
    username: root
    password: secret
  jpa:
    hibernate:
      ddl-auto: update
myapp:
  servers:
    - server1.example.com
    - server2.example.com
---
spring:
  profiles: dev
server:
  port: 9090

YAML vs Properties: A Detailed Comparison

Let's break down the technical differences. First, structure: .properties is flat and uses dots to represent hierarchy, while YAML uses indentation. For example, spring.datasource.url in .properties becomes spring: datasource: url: in YAML. Second, lists: .properties uses array notation (myapp.servers[0]), while YAML uses dashes (- server1). Third, profile support: Both support profile-specific files, but YAML also supports multi-document files. Fourth, type safety: Both work with @ConfigurationProperties, but YAML's nested structure maps more naturally to complex POJOs. Fifth, performance: .properties files are slightly faster to parse because they're simpler, but the difference is negligible for most applications. Sixth, compatibility: .properties is supported in all Spring versions, while YAML requires SnakeYAML (included by default in Spring Boot). Seventh, environment variables: Spring Boot can map environment variables to both formats, but YAML's nested keys can be tricky with environment variables (e.g., SPRING_DATASOURCE_URL). Eighth, error handling: YAML errors are often silent—Spring Boot will simply ignore malformed sections, while .properties files throw clear errors. Ninth, tooling: Most IDEs support both, but YAML formatting is more prone to IDE-specific quirks.

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

import java.util.List;

@Component
@ConfigurationProperties(prefix = "myapp")
public class AppConfig {
    private String name;
    private List<String> servers;
    private Database database = new Database();

    // getters and setters
    public static class Database {
        private String url;
        private String username;
        private String password;
        // getters and setters
    }
}

Profile-Specific Configuration: Best Practices

Both formats support profile-specific files, but there are nuances. In .properties, you create application-dev.properties, application-prod.properties, etc. In YAML, you can either create separate files (application-dev.yml) or use multi-document files. I recommend separate files for clarity. The spring.profiles.active property sets the active profile. You can also use spring.profiles.include to include multiple profiles. A common pattern is to have a base application.yml with common settings and then profile-specific files that override only what's necessary. For example, application-dev.yml might set server.port=9090 while application-prod.yml sets server.port=8080. Be careful with the order: Spring Boot loads the base file first, then the profile-specific file. This means profile-specific values override base values. Also, note that spring.profiles.active can be overridden by environment variables or command-line arguments, which is useful for CI/CD pipelines.

spring:
  profiles: dev
server:
  port: 9090
logging:
  level:
    com.example: DEBUG
myapp:
  environment: development

Advanced Configuration: Lists, Maps, and Nested Objects

Both formats support complex data structures, but YAML is much more readable. In .properties, lists use array notation: myapp.servers[0]=server1, myapp.servers[1]=server2. Maps use dotted notation: myapp.map.key1=value1. In YAML, lists use dashes: servers: - server1 - server2, and maps use nested keys: map: key1: value1. For nested objects like a database configuration, YAML is far more intuitive: database: url: jdbc:... username: root. In .properties, you'd write myapp.database.url=jdbc:.... Spring Boot's @ConfigurationProperties handles both formats seamlessly. However, there's a gotcha: if you have a list of objects, .properties requires index-based access (myapp.users[0].name=John), while YAML uses a list of maps: users: - name: John. Also, Spring Boot 3.1+ supports spring.config.import for importing other config files, which works with both formats but is more natural in YAML.

myapp:
  users:
    - name: John
      age: 30
    - name: Jane
      age: 25
  database:
    url: jdbc:mysql://localhost:3306/mydb
    credentials:
      username: root
      password: secret
  servers:
    - server1.example.com
    - server2.example.com

Migration Strategies: Moving from Properties to YAML (or Vice Versa)

Migrating between formats is straightforward but requires careful planning. Spring Boot supports both formats simultaneously, but you should avoid mixing them in the same project. To migrate, start by creating a new application.yml file and copy the content from your application.properties. You can use online converters, but they're not perfect—always review the output. For simple key-value pairs, the conversion is trivial: server.port=8080 becomes server: port: 8080. For lists, myapp.servers[0]=server1 becomes myapp: servers: - server1. For nested objects, spring.datasource.url=jdbc:... becomes spring: datasource: url: jdbc:.... After conversion, test thoroughly. Pay special attention to profile-specific files: convert application-dev.properties to application-dev.yml and ensure the spring.profiles property is correctly set. Also, check any @PropertySource annotations in your code—they need to reference the correct file extension. Finally, update your CI/CD pipeline to validate the new format. If you're migrating from YAML to .properties, the process is the reverse. In my experience, migrating to YAML is more common because teams want better readability.

import org.springframework.boot.SpringApplication;
import org.springframework.boot.env.PropertiesPropertySourceLoader;
import org.springframework.boot.env.YamlPropertySourceLoader;
import org.springframework.core.env.PropertySource;
import org.springframework.core.io.ClassPathResource;

import java.io.IOException;
import java.util.List;

public class MigrationTool {
    public static void main(String[] args) throws IOException {
        // Load properties file
        PropertiesPropertySourceLoader propertiesLoader = new PropertiesPropertySourceLoader();
        List<PropertySource<?>> properties = propertiesLoader.load("app", new ClassPathResource("application.properties"));
        
        // Load YAML file
        YamlPropertySourceLoader yamlLoader = new YamlPropertySourceLoader();
        List<PropertySource<?>> yaml = yamlLoader.load("app", new ClassPathResource("application.yml"));
        
        // Compare and print differences
        System.out.println("Properties source: " + properties.get(0).getSource());
        System.out.println("YAML source: " + yaml.get(0).getSource());
    }
}

Production Debugging: Common Configuration Issues

Configuration issues are a common source of production incidents. Here are the most common problems I've seen with both formats. YAML indentation errors: A single space can break your entire config. Use yamllint in your CI pipeline. Missing or extra quotes: YAML strings don't need quotes, but if they contain special characters like :, you need quotes. Profile not loading: If your profile-specific file isn't being loaded, check the spring.profiles.active property and the file name. Overriding issues: If a property isn't taking effect, check the order of configuration sources. Environment variables override file values. Type mismatch: If you define a list in YAML but your Java code expects a string, Spring Boot will throw a binding error. Silent failures: YAML files with syntax errors are often silently ignored. Always check the startup logs for warnings. Encoding issues: Ensure your files are saved as UTF-8. Non-ASCII characters in .properties files need to be escaped. File location: By default, Spring Boot looks for application.properties or application.yml in the classpath root. If you use a custom location, set spring.config.location explicitly.

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.event.ApplicationPreparedEvent;
import org.springframework.context.event.EventListener;

@SpringBootApplication
public class DebugApplication {
    public static void main(String[] args) {
        SpringApplication.run(DebugApplication.class, args);
    }
    
    @EventListener(ApplicationPreparedEvent.class)
    public void onApplicationPrepared(ApplicationPreparedEvent event) {
        System.out.println("Active profiles: " + String.join(", ", event.getApplicationContext().getEnvironment().getActiveProfiles()));
        System.out.println("server.port: " + event.getApplicationContext().getEnvironment().getProperty("server.port"));
    }
}

Conclusion: Which Format Should You Choose?

There's no one-size-fits-all answer. For simple applications with 10-20 configuration keys, use .properties. It's simpler, less error-prone, and works with older Spring versions. For complex applications with nested structures, lists, and multiple profiles, use YAML. It's more readable and maintainable. Consider your team's experience: if they're familiar with YAML from Docker or Kubernetes, it's a natural fit. If they're coming from older Java projects, .properties might be more comfortable. In microservices architectures, I lean towards YAML because it's easier to read configuration files that have 50+ keys. However, I always add a YAML linter to the CI pipeline. For monoliths, .properties is often sufficient. Ultimately, the best format is the one your team can maintain consistently. Whichever you choose, document your conventions and enforce them with code reviews. And remember: the most important thing is that your configuration is valid, secure, and easy to change.

import java.util.Scanner;

public class DecisionHelper {
    public static void main(String[] args) {
        Scanner scanner = new Scanner(System.in);
        System.out.print("How many config keys? ");
        int keys = scanner.nextInt();
        System.out.print("Do you have nested structures? (yes/no) ");
        String nested = scanner.next();
        
        if (keys < 20 && nested.equals("no")) {
            System.out.println("Recommendation: Use .properties");
        } else {
            System.out.println("Recommendation: Use YAML");
        }
        scanner.close();
    }
}