@ConfigurationProperties

@ConfigurationProperties is used in Spring Boot to bind external configuration values (from application.properties or application.yml) to a typed Java class.

Instead of reading properties one by one using @Value, this annotation allows you to map related properties into a structured object, making configuration clean, safe, and maintainable.

Why Use @ConfigurationProperties?

• Groups related configuration values together
• Avoids scattered @Value annotations
• Provides type safety and better readability
• Easy to manage large or complex configurations
• Works perfectly with YAML hierarchical structure

Basic Example

application.yml

app:
  name: My Spring App
  version: 1.0
  security:
    enabled: true

Configuration Class

@Component
@ConfigurationProperties(prefix = "app")
public class AppProperties {

    private String name;
    private String version;
    private Security security;

    public static class Security {
        private boolean enabled;

        // getters and setters
    }

    // getters and setters
}

How It Works

• prefix = "app" maps all properties starting with app
• app.name → name
• app.security.enabled → security.enabled

Spring Boot automatically binds values at startup.

Using with @EnableConfigurationProperties

If you don’t want to annotate the class with @Component:

@Configuration
@EnableConfigurationProperties(AppProperties.class)
public class AppConfig {
}

@ConfigurationProperties vs @Value

Spring Boot provides two common ways to read values from

application.properties or application.yml:

• @Value → Best for single or simple values
• @ConfigurationProperties → Best for grouped and complex configurations

Understanding the difference helps you write cleaner, scalable, and maintainable code.

1. Grouping of Properties

@ConfigurationProperties

• Designed to group related configuration values
• Maps multiple properties into one Java class
• Keeps configuration well-structured and organized

Example:

app:
  name: MyApp
  timeout: 30
  enabled: true

All these values are bound to one config class.

@Value

• Reads only one property at a time
• Configuration becomes scattered when many values are used
• Harder to manage as the application grows

2. Type Safety

@ConfigurationProperties

• Provides strong type safety
• Automatically converts values to correct data types
• Errors are caught at startup

Example:

private int timeout;
private boolean enabled;

@Value

• Type conversion is limited
• Runtime errors are more likely
• Harder to validate complex data

3. YAML Support

@ConfigurationProperties

• Excellent support for YAML
• Easily handles nested structures, lists, and maps
• Natural fit for hierarchical configs

@Value

• YAML support is limited
• Accessing nested values is verbose and messy
• Not suitable for complex YAML files

4. Large Configuration Handling

@ConfigurationProperties

• Ideal for large and enterprise-level applications
• Keeps configs modular and reusable
• Easy to combine with profiles (dev / test / prod)

@Value

• Not recommended for large configs
• Leads to cluttered code
• Difficult to maintain and refactor

5. Readability & Maintainability

@ConfigurationProperties

• Clean and readable configuration classes
• Easy to understand what config belongs where
• Preferred in professional Spring Boot projects

@Value

• Code becomes noisy with many annotations
• Hard to track configuration usage
• Lower readability in real-world apps

Comparison Table

Validation with @ConfigurationProperties

You can validate configuration values using @Validated.

@Component
@ConfigurationProperties(prefix = "app")
@Validated
public class AppProperties {

    @NotBlank
    private String name;

    @Min(1)
    private int timeout;

    // getters and setters
}

If validation fails, application startup will fail, preventing bad configuration.

When to Use @ConfigurationProperties

• Database, security, API, or external service configs
• Feature flags and application-level settings
• Large configuration blocks
• Multi-profile applications (dev, test, prod)

Best Practices

• Use one config class per feature/module
• Keep prefix names short and meaningful
• Prefer @ConfigurationProperties over @Value for multiple values
• Combine with profiles for environment-specific configs

Conclusion

• @ConfigurationProperties maps configuration files to Java objects
• Improves structure, safety, and maintainability
• Ideal for complex and hierarchical configuration
• A best practice for professional Spring Boot applications