@ConfigurationProperties

#Introduction

@ConfigurationProperties is the enterprise-standard way to bind external configuration into Java objects. Beginners often use @Value everywhere; experienced Spring Boot developers use @ConfigurationProperties for maintainable, type-safe and validated configuration.

Almost every enterprise application has configuration classes for the database, Redis, Kafka, RabbitMQ, JWT, AWS, Azure, SMTP, payment gateways, Elasticsearch and external APIs.

Interviewers frequently ask: What is @ConfigurationProperties? @Value vs @ConfigurationProperties? What is relaxed binding? What is constructor binding? How are nested objects, lists and maps bound? How does validation work? Which internal classes perform the binding?

#What is @ConfigurationProperties?

It binds a group of related configuration properties into a Java object.

mail.host=smtp.gmail.com
mail.port=587
mail.username=admin
mail.password=secret

Instead of writing:

@Value("${mail.host}")
private String host;

@Value("${mail.port}")
private int port;

@Value("${mail.username}")
private String username;

@Value("${mail.password}")
private String password;

use:

@ConfigurationProperties(prefix = "mail")
public class MailProperties {
    private String host;
    private int port;
    private String username;
    private String password;
    // getters and setters
}

Cleaner. Safer. The enterprise standard.

#Why Was It Introduced?

Imagine:

payment.timeout=30
payment.currency=USD
payment.retry=5
payment.api-key=abc123
payment.base-url=https://api.example.com
payment.max-connections=20
payment.read-timeout=5000
payment.connect-timeout=3000

With @Value, after 20–30 properties, maintenance becomes difficult. Instead: one PaymentProperties object holds all payment configuration.

#Basic Example

app:
  server:
    host: localhost
    port: 8080

@Component
@ConfigurationProperties(prefix = "app.server")
public class ServerProperties {
    private String host;
    private int port;
    // getters/setters
}

@Service
public class ServerService {

    private final ServerProperties properties;

    public ServerService(ServerProperties properties) {
        this.properties = properties;
    }
}

Internal Architecture

#Property Prefix

@ConfigurationProperties(prefix = "database")

Spring binds database.host, database.port, database.username and database.password. Only properties beginning with database are considered.

#Relaxed Binding

Interview favourite. Spring Boot understands multiple naming styles. For the Java field private int maxConnections; (with prefix payment), all of these bind:

payment.max-connections=20      (kebab-case — recommended in files)
payment.maxConnections=20       (camelCase)
payment.max_connections=20      (underscore)
PAYMENT_MAXCONNECTIONS=20       (environment variable)

Everything maps to maxConnections.

#Nested Objects

database:
  host: localhost
  pool:
    max-size: 30
    timeout: 5000

@ConfigurationProperties(prefix = "database")
public class DatabaseProperties {

    private String host;
    private Pool pool;

    public static class Pool {
        private int maxSize;
        private int timeout;
        // getters/setters
    }
}

#List Binding

application:
  roles:
    - ADMIN
    - USER
    - MANAGER

private List<String> roles;   // ADMIN, USER, MANAGER

No SpEL required.

#Map Binding

application:
  headers:
    Authorization: JWT
    Version: v1

private Map<String, String> headers;

Bound automatically.

#Duration, DataSize and Enums

cache:
  timeout: 30s

private Duration timeout;   // also: 5m, 2h, 1d

upload:
  max-file-size: 100MB

private DataSize maxFileSize;   // 100 MB

public enum Mode {
    DEV,
    PROD
}

// application.mode: PROD → Mode.PROD

All converted automatically.

Type Conversion

#Validation

Interview favourite.

@ConfigurationProperties(prefix = "mail")
@Validated
public class MailProperties {

    @NotBlank
    private String host;

    @Min(1)
    private int port;
}

With mail.port=-1, application startup fails. Very useful — configuration errors are caught at startup, not in production traffic.

#Constructor Binding

Spring Boot 3.x automatically uses constructor binding when a properties class has a single parameterized constructor, so an explicit @ConstructorBinding is unnecessary in most cases (it's only needed to pick one of several constructors).

@ConfigurationProperties(prefix = "payment")
public class PaymentProperties {

    private final String currency;
    private final int timeout;

    public PaymentProperties(String currency, int timeout) {
        this.currency = currency;
        this.timeout = timeout;
    }

    public String getCurrency() {
        return currency;
    }

    public int getTimeout() {
        return timeout;
    }
}

Benefits: immutable, thread-safe, easier testing. A Java record works the same way and is even shorter:

@ConfigurationProperties(prefix = "payment")
public record PaymentProperties(String currency, int timeout) {
}

#Registration

There are three common ways to turn the class into a bean:

// 1. As a component
@Component
@ConfigurationProperties(prefix = "mail")

// 2. Explicitly
@EnableConfigurationProperties(MailProperties.class)

// 3. By scanning — Spring scans all configuration-property classes
@ConfigurationPropertiesScan

(Constructor-bound classes and records can't use @Component; register them with option 2 or 3.)

#Internal Binding Flow

Important Internal Classes

#Metadata Generation

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>

This generates metadata that gives your IDE auto-completion, documentation and property validation for your custom configuration properties.

#@Value vs @ConfigurationProperties

Enterprise recommendation: few properties → @Value; many properties → @ConfigurationProperties.

#Enterprise Example

#Real Enterprise Structure

#Key Takeaways

• @ConfigurationProperties is the preferred way to manage structured configuration.
• It binds related properties into a single, strongly typed object.
• Relaxed binding maps multiple naming conventions to the same field.
• Nested objects, collections, maps, Duration, DataSize and enums bind automatically.
• Constructor binding with immutable classes (or records) is recommended in Boot 3.
• Validation catches configuration errors at startup.
• Binder and ConfigurationPropertiesBindingPostProcessor power the binding.