If your team argues about application.properties versus application.yml you are not alone. Both files are first class citizens in Spring Boot and Spring will happily read either from the classpath. The real difference is formatting and ergonomics not some mystical badge of honor.

Quick summary you can actually use

Short version with a wink. Use application.properties when you want flat key value pairs that are compact and familiar. Use application.yml when you need nested maps or lists and you dislike repeated prefixes. Both support profiles and both bind to @ConfigurationProperties or @Value the same way.

Format and structure

Properties files are simple. One key equals one value. They work well for small, flat settings and for legacy tools that expect equals sign parsing.

server.port=8080
spring.datasource.username=dbuser

YAML gives you hierarchy with indentation which is easier to read when things get nested or when lists enter the party.

server:
  port: 8080
spring:
  datasource:
    username: dbuser

Lists and maps without tears

YAML wins for readability when you have arrays or nested maps. You can still use indexed properties in .properties but the verbosity climbs fast.

# YAML list example
app:
  servers:
    - host: s1.example.com
      port: 9001
    - host: s2.example.com
      port: 9002

# Properties equivalent
app.servers[0].host=s1.example.com
app.servers[0].port=9001
app.servers[1].host=s2.example.com
app.servers[1].port=9002

Profiles and precedence in Spring Boot

Profiles work the same no matter the file format. Put profile specific values in files named application-dev.properties or application-dev.yml and Spring will pick the one that matches the active profile. Spring Environment resolves placeholders and binds values to beans using the same rules for both formats.

Debugging configuration like a detective

Stop blaming the build system. Enable startup debug so Spring tells you which file supplied a property. Start the app with --debug or set debug=true and inspect the startup logs. This saves time and elbow grease.

Practical best practices

• Prefer YAML for deep nesting and lists to keep configs readable.
• Prefer properties for tiny apps and when tooling expects flat keys.
• Keep secret handling out of plain files and use a vault or environment variables.
• Use profile specific files rather than huge conditional blocks when possible.
• Consistency beats cleverness. Pick one format per project unless you have a good reason.

Real world pick guide

If most of your configuration is flat and your CI or old scripts parse equals signs stick with application.properties. If your config has nested maps, lists, or you want fewer noisy prefixes choose application.yml. Either choice is supported by Spring so aim for a setup that makes the next developer smile and not cry.