If you’ve ever ended up with a dozen @Value annotations and no idea which settings are required, @ConfigurationProperties is the Spring Boot way to make configuration type-safe, structured, and validatable.
In this post, you’ll learn:
application-{profile}.yml) override defaults@ConfigurationProperties?In this section, we clarify Why @ConfigurationProperties? and summarize the key points you will apply in implementation.
In this section, we clarify Prerequisites and summarize the key points you will apply in implementation.
application.ymlCreate a namespace (prefix) for your app config, for example app:
app: security: enabled: true token-expiry-seconds: 3600 allowed-origins: - 'https://example.com' - 'http://localhost:3000'
@ConfigurationProperties classYou have two common options:
@ConfigurationProperties types:import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.boot.context.properties.ConfigurationPropertiesScan; @SpringBootApplication @ConfigurationPropertiesScan public class DemoApplication {}
import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.boot.context.properties.EnableConfigurationProperties; @SpringBootApplication @EnableConfigurationProperties(AppProperties.class) public class DemoApplication {}
Add validation constraints and annotate the class with @Validated.
Note: you need a Bean Validation implementation on the classpath (e.g., spring-boot-starter-validation) for these constraints to be enforced.
application-{profile}.yml)Spring Boot loads application.yml and then applies profile-specific overrides.
Example:
application.yml (defaults)application-prod.yml (production overrides)# application-prod.yml app: security: enabled: true allowed-origins: - 'https://mycompany.com'
When multiple profiles are active, profile files are applied with a “last wins” strategy (the last active profile can override earlier ones).
In this section, we clarify Tips and summarize the key points you will apply in implementation.
@ConfigurationProperties over scattered @Value for anything non-trivial.AppProperties root per bounded domain (security, mail, storage, etc.).You now have a type-safe Spring Boot configuration layer with startup validation and profile-based overrides. As a next step, externalize environment-specific secrets and add configuration tests to catch regressions early.
import java.util.List; import org.springframework.boot.context.properties.ConfigurationProperties; @ConfigurationProperties(prefix = "app") public class AppProperties { private Security security = new Security(); private List<String> allowedOrigins = List.of(); public Security getSecurity() { return security; } public void setSecurity(Security security) { this.security = security; } public List<String> getAllowedOrigins() { return allowedOrigins; } public void setAllowedOrigins(List<String> allowedOrigins) { this.allowedOrigins = allowedOrigins; } public static class Security { private boolean enabled = true; private int tokenExpirySeconds = 3600; public boolean isEnabled() { return enabled; } public void setEnabled(boolean enabled) { this.enabled = enabled; } public int getTokenExpirySeconds() { return tokenExpirySeconds; } public void setTokenExpirySeconds(int tokenExpirySeconds) { this.tokenExpirySeconds = tokenExpirySeconds; } } }
import org.springframework.boot.context.properties.ConfigurationProperties @ConfigurationProperties(prefix = "app") data class AppProperties( val security: Security = Security(), val allowedOrigins: List<String> = emptyList(), ) { data class Security( val enabled: Boolean = true, val tokenExpirySeconds: Int = 3600, ) }
import java.util.List; import jakarta.validation.Valid; import jakarta.validation.constraints.Min; import jakarta.validation.constraints.NotEmpty; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.validation.annotation.Validated; @ConfigurationProperties(prefix = "app") @Validated public class AppProperties { @Valid private Security security = new Security(); @NotEmpty private List<String> allowedOrigins = List.of(); public Security getSecurity() { return security; } public void setSecurity(Security security) { this.security = security; } public List<String> getAllowedOrigins() { return allowedOrigins; } public void setAllowedOrigins(List<String> allowedOrigins) { this.allowedOrigins = allowedOrigins; } public static class Security { private boolean enabled = true; @Min(60) private int tokenExpirySeconds = 3600; public boolean isEnabled() { return enabled; } public void setEnabled(boolean enabled) { this.enabled = enabled; } public int getTokenExpirySeconds() { return tokenExpirySeconds; } public void setTokenExpirySeconds(int tokenExpirySeconds) { this.tokenExpirySeconds = tokenExpirySeconds; } } }
import jakarta.validation.Valid import jakarta.validation.constraints.Min import jakarta.validation.constraints.NotEmpty import org.springframework.boot.context.properties.ConfigurationProperties import org.springframework.validation.annotation.Validated @ConfigurationProperties(prefix = "app") @Validated data class AppProperties( @field:Valid val security: Security = Security(), @field:NotEmpty val allowedOrigins: List<String> = emptyList(), ) { data class Security( val enabled: Boolean = true, @field:Min(60) val tokenExpirySeconds: Int = 3600, ) }