Are you still configuring every Spring Boot application with a giant application.properties file?

There's nothing wrong with that. Spring Boot fully supports traditional Java properties files, and for small applications they can be refreshingly simple.

But once configuration becomes hierarchical, with nested properties, lists, profiles and groups of related settings, an application.yml file can be significantly easier to read.

So which Spring Boot configuration format should you use?

Let's compare them.

Spring Boot YAML vs. properties

Spring Boot supports both of these common configuration formats:

  1. application.properties
  2. application.yml or application.yaml

From Spring Boot's perspective, both ultimately provide configuration properties to the Spring Environment.

That means there isn't a special set of Spring Boot features available only to YAML users. If you can configure something in application.properties, you can normally express the same configuration in YAML.

The real difference is how that configuration is written and organized.

Spring application.yml example

Here's an application.yml file that configures:

  • the embedded web server;
  • Spring Boot itself;
  • Spring Boot DevTools; and
  • a few custom application properties.
server:
  port: 8099

spring:
  application:
    name: MyYamlAppName
  devtools:
    restart:
      enabled: false
  main:
    banner-mode: "off"

favorite:
  ca:
    city: Montreal
    actors:
      - William Shatner
      - John Candy

One of YAML's biggest advantages becomes obvious immediately: related configuration is grouped into a hierarchy.

Everything related to spring appears together. Everything related to favorite.ca appears together. And the list of great Canadian actors actually looks like a list.

William Shatner and John Candy deserve nothing less.

The same configuration in application.properties

Here's essentially the same configuration expressed with a traditional application.properties file:

server.port=8099

spring.application.name=MyPropertiesAppName
spring.devtools.restart.enabled=false
spring.main.banner-mode=off

favorite.ca.city=Montreal
favorite.ca.actors[0]=William Shatner
favorite.ca.actors[1]=John Candy

There's nothing wrong with this format. In fact, for a handful of properties, I might argue that it's simpler.

But notice the repetition:

favorite.ca.actors[0]=William Shatner
favorite.ca.actors[1]=John Candy

YAML represents that same list more naturally:

favorite:
  ca:
    actors:
      - William Shatner
      - John Candy

As the configuration hierarchy grows, YAML tends to become increasingly attractive.

How Spring Boot interprets YAML

Spring Boot doesn't fundamentally treat these as completely different properties.

For example, this YAML:

favorite:
  ca:
    city: Montreal
    actors:
      - William Shatner
      - John Candy

is effectively flattened into properties that look like this:

favorite.ca.city=Montreal
favorite.ca.actors[0]=William Shatner
favorite.ca.actors[1]=John Candy

That's why the same Spring Boot configuration APIs can work regardless of whether the underlying configuration was written as YAML or as a properties file.

Bind application.yml to a Java class

YAML becomes especially useful when Spring Boot's @ConfigurationProperties feature is used to bind hierarchical configuration to Java objects.

For example, the favorite.ca configuration can be represented with a Java record:

import java.util.List;

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

@ConfigurationProperties(prefix = "favorite.ca")
public record FavoriteCanadaProperties(
    String city,
    List<String> actors
) {
}

The corresponding YAML remains pleasantly simple:

favorite:
  ca:
    city: Montreal
    actors:
      - William Shatner
      - John Candy

Spring Boot can bind the nested configuration directly to the FavoriteCanadaProperties record.

For structured application configuration, this combination of YAML and @ConfigurationProperties is particularly clean.

Use environment variables in application.yml

Hard-coding every environment-specific value directly into application.yml isn't a great idea.

For example, database passwords, service URLs and deployment-specific settings will often come from the environment in which the application runs.

Spring Boot property placeholders make that easy:

spring:
  datasource:
    url: ${DB_URL}
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}

server:
  port: ${SERVER_PORT:8080}

The SERVER_PORT example also provides a default. If the environment variable isn't defined, the application uses port 8080.

The same technique works in application.properties:

spring.datasource.url=${DB_URL}
spring.datasource.username=${DB_USERNAME}
spring.datasource.password=${DB_PASSWORD}

server.port=${SERVER_PORT:8080}

Again, this isn't a capability unique to YAML. It's simply another case where YAML can make a group of related settings easier to visually organize.

Spring Boot YAML and profiles

Spring Boot profiles work naturally with YAML.

For example, you might have a base configuration in:

application.yml

and production-specific overrides in:

application-prod.yml

The base file might contain:

spring:
  application:
    name: MyYamlAppName

server:
  port: 8080

Then application-prod.yml could override the port:

server:
  port: 8099

Activate the production profile with:

spring.profiles.active=prod

or externally through an environment variable:

SPRING_PROFILES_ACTIVE=prod

This lets the same application artifact run with different configuration in development, testing and production.

Multiple profiles in one YAML file

YAML also supports multiple documents in one file. Spring Boot can conditionally activate those documents according to the active profile.

server:
  port: 8080

---
spring:
  config:
    activate:
      on-profile: dev

server:
  port: 8081

---
spring:
  config:
    activate:
      on-profile: prod

server:
  port: 80

With no matching profile, the application uses port 8080. The dev profile changes it to 8081, while prod changes it to port 80.

This can be convenient for smaller applications, although separate application-dev.yml and application-prod.yml files are often easier to navigate when configuration becomes large.

The @PropertySource YAML limitation

There is one Spring configuration limitation worth knowing about.

Spring's standard @PropertySource annotation does not directly load YAML files.

So this is not a supported way to import an arbitrary YAML property source:

@Configuration
@PropertySource("classpath:favorites.yaml")
public class FavoritesConfig {
}

If you specifically need @PropertySource, a traditional properties file is the simpler choice.

For normal Spring Boot application configuration, however, this usually isn't a problem. Spring Boot already understands application.yml, profile-specific YAML files and configuration data imports.

What are the disadvantages of YAML?

I'm a fan of YAML for structured Spring Boot configuration, but it's not automatically better in every situation.

There are a few drawbacks.

YAML is whitespace-sensitive

This is valid:

spring:
  application:
    name: MyApp

Indentation defines the hierarchy. Get the indentation wrong and you can change the meaning of the document or make it invalid.

A properties file doesn't have that problem:

spring.application.name=MyApp

Small configuration files don't need a hierarchy

If your entire application configuration contains five settings, YAML's nested structure might actually be more verbose.

This:

server.port=8080
spring.application.name=MyApp

is arguably simpler than:

server:
  port: 8080

spring:
  application:
    name: MyApp

Deeply nested YAML can become difficult to scan

YAML eliminates repeated property prefixes, but deeply nested configuration can create its own readability problems.

Good configuration design still matters regardless of the file format.

Benefits of Spring Boot application.yml

So why do many Spring Boot developers prefer YAML?

  • Hierarchical configuration is visually obvious.
  • Repeated property prefixes disappear.
  • Lists are easy to express and read.
  • Nested configuration maps naturally to @ConfigurationProperties.
  • Multiple YAML documents can support profile-specific configuration.
  • The syntax is familiar to developers who also work with Kubernetes, Docker Compose, CI/CD systems and other YAML-based tools.
Spring Boot application.properties vs application.yml files

Which do you prefer: Spring Boot application.yml or application.properties?

Can application.yml and application.properties be used together?

Technically, yes.

Spring Boot can encounter configuration in both YAML and properties formats. However, mixing the two formats for the same application configuration tends to make the project harder to understand.

If both an application.properties file and a YAML application file exist in the same location, Spring Boot gives the .properties file precedence.

That's an important detail, but it shouldn't be treated as an invitation to maintain both formats side by side.

Pick one format for your application's main configuration and stay consistent.

Should you use application.yml or application.properties?

For a tiny Spring Boot project with a handful of settings, application.properties is difficult to beat. It's simple, familiar and almost impossible to misunderstand.

But as an application grows and its configuration starts to include nested objects, lists, profiles and related groups of settings, I tend to prefer application.yml.

Just compare these two Canadian masterpieces:

favorite.ca.city=Montreal
favorite.ca.actors[0]=William Shatner
favorite.ca.actors[1]=John Candy

and:

favorite:
  ca:
    city: Montreal
    actors:
      - William Shatner
      - John Candy

They configure the same information.

But when configuration becomes hierarchical, YAML often communicates the structure more clearly. That's the real benefit of Spring Boot's application.yml file.