Type-Safe Configuration with @ConfigurationProperties

Injecting individual properties with @Value("${property.key}") creates brittle architectures: keys are hardcoded strings, syntax errors fail only when individual beans are accessed, and there is no centralized schema. In modern Spring Boot (3.0+), the gold standard is @ConfigurationProperties paired with immutable Java records and constructor binding.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

package com.example.config;

import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;

import java.time.Duration;

@ConfigurationProperties(prefix = "app.mail")
@Validated
public record MailProperties(
    @NotBlank String host,
    @Min(1) @Max(65535) int port,
    @NotBlank String username,
    @NotBlank String password,
    @NotNull Duration timeout,
    boolean starttls
) {
    public MailProperties {
        if (timeout == null) {
            timeout = Duration.ofSeconds(5);
        }
    }
}

By enabling @EnableConfigurationProperties(MailProperties.class) or relying on @ConfigurationPropertiesScan, Spring Boot discovers the record, binds properties matching the app.mail prefix directly to constructor arguments, and registers the immutable record as a singleton bean.

Annotating a @ConfigurationProperties class or record with @Validated instructs Spring Boot to execute the Jakarta Validation engine (Hibernate Validator) during application startup. If any constraint is violated (e.g. port is 0 or host is blank), Boot aborts startup immediately with a clear error report before any HTTP requests or database connections are opened.

Spring Boot contains an advanced ApplicationConversionService that converts plain string properties into rich domain types without manual parsing.

Let us observe what happens when a property fails validation. Suppose app.mail.port is set to -1 or omitted when annotated with @Min(1).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

***************************
APPLICATION FAILED TO START
***************************

Description:

Binding to target org.springframework.boot.context.properties.bind.BindResult@7f3b84 failed:

    Property: app.mail.port
    Value: -1
    Origin: class path resource [application.yml] - 4:11
    Reason: must be greater than or equal to 1

Action:

Update your application's configuration