Here is the English translation. Note: the Japanese source contains an accidentally duplicated fragment (details after the translation) — I’ve translated it faithfully as-is per your rules, but you’ll likely want to remove it from both language versions.

When developing a Spring Boot application, you need to manage a variety of settings such as database connection information, the server port, and log levels. The configuration files that manage these settings are application.properties and application.yml.

For beginners, however, the questions never end: “Which file format should I use?”, “How do I read environment variables?”, “When should I use @Value versus @ConfigurationProperties?”

In this article, we’ll walk through everything from configuration file basics to how to choose the right approach in real-world work.

Configuration File Basics - properties and yml

Spring Boot configuration files externalize settings such as database connection information and the server port. Place them in the src/main/resources directory and they are loaded automatically.

The two main formats are application.properties (key=value format) and application.yml (YAML format).

# application.properties
server.port=8080
spring.datasource.url=jdbc:mysql://localhost:3306/mydb
# application.yml
server:
  port: 8080
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mydb

For simple configurations, properties is fine; for deeply nested configurations, yml is easier to read. What matters most, however, is matching the format your existing project already uses. If both files exist, properties takes precedence.

Reading a Single Configuration Value with @Value

The simplest way to use configuration values in Java code is the @Value annotation.

# application.properties
app.name=MySpringBootApp
app.timeout=30
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

@Component
public class AppConfig {
    @Value("${app.name}")
    private String appName;

    @Value("${app.timeout:30}")  // 未定義なら30を使用
    private int timeout;
}

@Value is convenient for reading a single configuration value, but when you have many related settings, @ConfigurationProperties (covered next) is a better fit.

When you have multiple related properties, grouping them with @ConfigurationProperties makes them type-safe and easier to manage.

# application.yml
app:
  database:
    host: localhost
    port: 3306
@ConfigurationProperties(prefix = "app.database")
public record DatabaseProperties(String host, int port) {}

Enable it in your main class and use it.

@SpringBootApplication
@EnableConfigurationProperties(DatabaseProperties.class)
public class MyApplication { ... }

@Service
public class DatabaseService {
    private final DatabaseProperties props;
    // コンストラクタで注入して使える
}

For a single configuration value, @Value is sufficient; for a group of related settings, @ConfigurationProperties is the right choice.

Validating @ConfigurationProperties Values

Mistakes in configuration values, if left unchecked, surface as runtime errors after startup. By adding @Validated to a @ConfigurationProperties class, you can validate configuration values at startup using Bean Validation (jakarta.validation) annotations — if any value is invalid, the application refuses to start (fail-fast).

First, add spring-boot-starter-validation to your dependencies.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

Add constraint annotations to the properties you want to validate.

import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import org.springframework.validation.annotation.Validated;

@Validated
@ConfigurationProperties(prefix = "app.database")
public record DatabaseProperties(
        @NotBlank String host,
        @Min(1) @Max(65535) int port
) {}

If a value violates a constraint, a BindValidationException is thrown at startup, and the log shows which property violated which constraint. Because this lets you catch configuration mistakes the moment the application starts rather than after it’s running in production, we recommend always pairing @ConfigurationProperties with validation.

Note that this mechanism does not apply to @Value. Move any settings that need validation over to @ConfigurationProperties.

Binding Lists and Maps, and IDE Completion

@ConfigurationProperties can bind not only simple values but also List and Map directly.

app:
  servers:
    - host1.example.com
    - host2.example.com
  timeouts:
    connect: 5
    read: 30
@ConfigurationProperties(prefix = "app")
public record AppProperties(
        List<String> servers,
        Map<String, Integer> timeouts
) {}

As your property classes grow in number, instead of listing them one by one in @EnableConfigurationProperties, you can add @ConfigurationPropertiesScan to your main class to scan entire packages, which makes them easier to manage.

Also, if you add spring-boot-configuration-processor as a dependency (annotationProcessor), metadata is generated at build time, enabling completion and documentation hints for your custom properties in the IDE. This is effective at preventing configuration mistakes in team development.

application.yml

app: database: host: localhost port: 3306


```java
@ConfigurationProperties(prefix = "app.database")
public record DatabaseProperties(String host, int port) {}

Enable it in your main class and use it.

@SpringBootApplication
@EnableConfigurationProperties(DatabaseProperties.class)
public class MyApplication { ... }

@Service
public class DatabaseService {
    private final DatabaseProperties props;
    // コンストラクタで注入して使える
}

For a single configuration value, @Value is sufficient; for a group of related settings, @ConfigurationProperties is the right choice.

Overriding Production Settings with Environment Variables

Sensitive information such as passwords should be managed with environment variables. Convert the dots and hyphens in a property name to underscores and lowercase letters to uppercase, and the variable is picked up automatically.

For example, spring.datasource.password can be overridden with the environment variable SPRING_DATASOURCE_PASSWORD.

spring:
  datasource:
    password: ${DB_PASSWORD:defaultpassword}
export DB_PASSWORD=super-secure-password
java -jar myapp.jar

Beyond overriding with environment variables, if you want to safely place encrypted secrets in the configuration file itself, see “How to Encrypt Sensitive Configuration Values in Spring Boot with Jasypt”. For injecting configuration from ConfigMaps and Secrets on Kubernetes, see “How to Deploy a Spring Boot Application to Kubernetes”.

Environment Variable Name Conversion Rules (Relaxed Binding)

The mechanism by which Spring Boot maps environment variables to properties is called relaxed binding. The conversion to an environment variable name follows three steps:

  1. Replace dots (.) with underscores (_)
  2. Remove hyphens (-)
  3. Convert everything to uppercase

Here are some conversion examples.

Property nameEnvironment variable name
spring.datasource.passwordSPRING_DATASOURCE_PASSWORD
app.base-urlAPP_BASEURL
server.servlet.context-pathSERVER_SERVLET_CONTEXTPATH

Note that hyphens are removed, not converted to underscores. If you write APP_BASE_URL, it is interpreted as app.base.url and will not bind to app.base-url. When an environment variable doesn’t seem to take effect, checking this conversion rule first will often lead you to the answer quickly.

Reusing Configuration Values with Placeholders

You can reference other property values with the ${} placeholder.

app.base-url=https://api.example.com
app.endpoint.users=${app.base-url}/users

# 環境変数が未定義ならデフォルト値を使用
server.port=${SERVER_PORT:8080}

Understanding Property Precedence

When configuration is loaded from multiple sources, the precedence is as follows (higher in the list wins):

  1. Command-line arguments
  2. OS environment variables
  3. application-{profile}.properties/yml
  4. application.properties/yml

To switch settings per environment, use Profiles.

java -jar myapp.jar --spring.profiles.active=prod

For details on Profiles, see “How to Safely Switch Environment-Specific Configuration with Spring Boot Profiles”.

Common Pitfalls

Here are some errors you’re likely to run into with configuration files.

Properties won’t load

If @Value displays ${key} as-is, you may have a typo in the key name, or the class may be missing @Component. Also check that the configuration file is in src/main/resources.

YAML indentation errors

YAML does not allow tab characters. Standardize on 2-space indentation. Using your IDE’s YAML support lets you catch errors in advance.

Environment variables not taking effect

Environment variable names must have dots and hyphens converted to underscores and lowercase converted to uppercase — for example, SPRING_DATASOURCE_PASSWORD rather than spring.datasource.password.

Frequently Asked Questions (FAQ)

Q. What is application.properties?

A. It is a configuration file for defining a Spring Boot application’s runtime settings (server port, database connection information, log levels, and so on) outside of your code. Place it in src/main/resources and it is loaded automatically at startup, letting you change behavior per environment without modifying code.

Q. Should I use application.properties or application.yml?

A. There is almost no functional difference, so the most important thing is consistency within your team and project. If you have many deeply nested settings, YAML is easier to scan; if your configuration is flat and small, properties is sufficient. If both files exist, the values in application.properties take precedence.

Q. What is the difference between @Value and @ConfigurationProperties?

A. @Value injects a single configuration value into one field at a time, whereas @ConfigurationProperties binds related settings sharing the same prefix into a single type-safe class. Startup-time validation with @Validated and metadata generation for IDE completion are only available with @ConfigurationProperties, so if you have two or more related settings, choosing @ConfigurationProperties is the standard practice in real-world work.

Q. If a value exists in both an environment variable and the configuration file, which wins?

A. OS environment variables take precedence over configuration files. The overall order of precedence is: command-line arguments > OS environment variables > profile-specific configuration files > application.properties/yml. This mechanism is what allows password overrides via environment variables to work in production.

Summary

Spring Boot configuration management is a simple mechanism: externalize settings into properties or yml files and read them with @Value or @ConfigurationProperties.

In production, override sensitive information such as passwords with environment variables, and use Profiles to switch settings per environment. Understanding property precedence helps you prevent unintended configuration overrides.

In real-world work, keep the following in mind:

  • Manage secrets with environment variables instead of writing them in configuration files
  • Group related settings with @ConfigurationProperties
  • Standardize the configuration file format within your team

Once you have the basics of configuration management down, you’ll be able to build applications that adapt flexibly to differences between environments.

Source issue worth fixing: the Japanese body contains a duplicated fragment right after the “Binding Lists and Maps, and IDE Completion” section — a repeat of the app.database YAML example, the DatabaseProperties record, and the @EnableConfigurationProperties example, and it starts with a broken code fence (the opening ```yaml is missing, so # application.yml renders as an H1 heading). I translated it verbatim per the “keep formatting intact” rule, but it should be deleted from both the Japanese source and this English version. Also, per your rules I left the three internal links pointing at /ja/... unchanged; if the English site expects /en/ links, that’s a separate substitution to make.