Application Properties and YAML Basics in Spring Boot 3

Introduction

Configuration is where Spring Boot becomes truly practical: you can change runtime behavior without changing Java code. In this chapter, you will learn how application.properties and application.yml work, when to choose each format, and how to configure common settings such as port, context path, logging level, and custom business values.

Prerequisites

  • Completed:
    • 01_what_is_spring_boot.md
    • 02_installing_java_maven_and_idea.md
    • 03_create_first_spring_boot_project.md
  • A runnable Spring Boot 3 project

Why Externalized Configuration Matters

In real projects, values change across environments:

  • Local database URL vs production database URL
  • Debug logging in development vs warning/error in production
  • Different ports for local testing and deployment

Spring Boot encourages externalized configuration, so these values live outside Java classes whenever possible.

Benefits:

  • Easier environment switching
  • Safer deployments
  • Cleaner code (business logic not mixed with environment data)

Two Main Formats: .properties vs .yml

Spring Boot supports both formats:

FormatStrengthsTrade-offs
application.propertiesSimple key-value, explicit and familiarNested structures become long and repetitive
application.ymlBetter readability for nested configIndentation-sensitive, easy to break with spacing errors

Both formats represent the same configuration model. You usually choose one style per project and stay consistent.

Tip

Team Rule

Pick one primary format (.properties or .yml) in each repository to reduce confusion in reviews.

File Location and Loading

Default config files live in:

text
src/main/resources/
  application.properties
  # or
  application.yml

Spring Boot loads configuration during startup. If both files exist, both can contribute values (with precedence rules), but avoid mixing unless you intentionally need it.

Basic Configuration Examples

Option A: application.properties

properties
# Set server port
server.port=8081
 
# Set context path
server.servlet.context-path=/api
 
# Set logging level for your package
logging.level.com.hellocode.demo=DEBUG
 
# Custom business config
app.welcome-message=Hello from configuration

Option B: application.yml

yaml
server:
  port: 8081
  servlet:
    context-path: /api
 
logging:
  level:
    com.hellocode.demo: DEBUG
 
app:
  welcome-message: Hello from configuration

These two snippets are functionally equivalent.

Read Custom Config in Code

Use @Value for simple values:

Code explanation:

  • ${app.welcome-message} reads the config value by key
  • Changing config value does not require code changes

Common Built-In Keys You Should Know

Frequently used keys:

  • server.port
  • server.servlet.context-path
  • spring.application.name
  • logging.level.*
  • spring.datasource.* (covered in data chapters)

You can discover many more in Spring Boot official docs.

Property Source Precedence (Beginner Version)

When the same key appears in multiple places, one value wins. A practical order (high level):

  1. Command-line args (--server.port=9090)
  2. Environment variables
  3. External config files (outside JAR)
  4. Internal config files (src/main/resources)
  5. Default value in code (if any)

This is why a value may look “ignored” in your local file—another source might override it.

Warning

Never hardcode secrets (passwords, tokens, API keys) in Git-tracked config files. Use environment variables or secure secret management.

Run with Temporary Overrides

You can override values at runtime:

bash
mvn spring-boot:run -Dspring-boot.run.arguments="--server.port=9090 --app.welcome-message=Hi"

Or for packaged JAR:

bash
java -jar demo-0.0.1-SNAPSHOT.jar --server.port=9090 --app.welcome-message=Hi

Great for quick testing without editing files.

Debugging Configuration Problems

Placeholder cannot be resolved

Example error:

text
Could not resolve placeholder 'app.welcome-message'

Check:

  • Key spelling
  • Correct file location (src/main/resources)
  • Correct active profile (next chapter)

YAML parse errors

Common reasons:

  • Wrong indentation
  • Tabs instead of spaces
  • Missing : after key

Value not taking effect

Likely overridden by:

  • Command-line arguments
  • Environment variables
  • Another profile file

Best Practices

  • Keep key naming consistent (kebab-case is common)
  • Group related keys under a namespace (app.*, feature.*)
  • Prefer type-safe binding with @ConfigurationProperties for larger config groups (covered later)
  • Avoid mixing unrelated config concerns in one giant file

Quick Recap

In this chapter, you learned:

  1. Why externalized config is essential
  2. How .properties and .yml compare
  3. How to define and read custom config values
  4. How override precedence affects runtime behavior

This foundation is required before multi-environment profiles.

FAQ

Should I choose properties or YAML?

Both are valid. YAML is cleaner for nested config; properties is explicit and easy for small apps. Choose one style per repo.

Can I keep both application.properties and application.yml?

Technically yes, but not recommended unless you clearly manage precedence. Mixed formats increase troubleshooting complexity.

Is @Value enough for all config needs?

For a few keys, yes. For larger structured config, prefer @ConfigurationProperties to get type-safe binding and validation.

Why does changing config sometimes require restart?

Standard Spring Boot apps read config at startup. Runtime refresh needs extra mechanisms (for example Spring Cloud Config patterns), which are outside this basic chapter.

Can I store credentials in application.yml?

You can, but you should avoid committing them. Use environment variables or secret management in real projects.