Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/spring-projects/spring-boot/llms.txt

Use this file to discover all available pages before exploring further.

Spring Boot lets you externalize configuration so the same application binary runs correctly in different environments. You can supply configuration through Java properties files, YAML files, OS environment variables, and command-line arguments — and Spring Boot resolves all of them through a single Environment abstraction.

​
Property source precedence

Spring Boot applies a well-defined ordering so that later sources can override earlier ones. The most important levels from lowest to highest priority are:
Set programmatically via SpringApplication.setDefaultProperties(Map). These are always the lowest-priority source.
application.properties and application.yaml files, loaded from the classpath root, the classpath /config package, the current directory, and subdirectories of config/. Profile-specific variants (e.g., application-prod.properties) always override the non-specific file.
Useful in containerized environments. Spring Boot performs relaxed binding, so SPRING_DATASOURCE_URL maps to spring.datasource.url.
Properties set via -Dproperty=value on the JVM command line.
Arguments starting with -- (e.g., --server.port=9000) are the highest-priority source among non-test sources. Spring Boot converts them to properties and adds them to the Environment.
Stick to a single format across your entire application. When both .properties and .yaml files exist in the same location, .properties takes precedence.

​
application.properties vs application.yaml

Both formats are supported. Spring Boot automatically finds and loads them from the classpath and the current directory. 
spring.application.name=MyApp
server.port=8080
spring.datasource.url=jdbc:postgresql://localhost/mydb
YAML’s hierarchical structure makes it easier to read deeply nested configuration. Spring Boot flattens YAML into the standard dot-separated property key format when loading it into the Environment.

​
Importing additional config files

Use spring.config.import to pull in configuration from additional locations: 
spring:
  application:
    name: "myapp"
  config:
    import: "optional:file:./dev.properties"
Values from the imported file take precedence over the file that declared the import. The optional: prefix prevents startup failure when the file does not exist.

​
Injecting values with @Value

@Value is the simplest way to inject a single property into a bean field or constructor parameter: 
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

@Component
public class MyBean {

    @Value("${name}")
    private String name;

}
You can provide a default value after a colon: ${name:World}.
Use kebab-case canonical names in @Value expressions (e.g., ${my.property-name}) so Spring Boot’s relaxed binding rules apply consistently across property files and environment variables.

​
Type-safe configuration with @ConfigurationProperties

For hierarchical or multi-property configuration, @ConfigurationProperties binds a whole group of related properties to a strongly typed Java class. This is safer and more maintainable than scattering @Value annotations across your codebase.

​
JavaBean-style binding

import java.net.InetAddress;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties("my.service")
public class MyProperties {

    private boolean enabled;

    private InetAddress remoteAddress;

    private final Security security = new Security();

    // getters and setters ...

    public static class Security {

        private String username;

        private String password;

        private List<String> roles = new ArrayList<>(Collections.singleton("USER"));

        // getters and setters ...

    }

}
The above class maps these properties:
PropertyTypeDefault
my.service.enabledbooleanfalse
my.service.remote-addressInetAddress—
my.service.security.usernameString—
my.service.security.passwordString—
my.service.security.rolesList<String>["USER"]

​
Enabling @ConfigurationProperties types

Register the type either explicitly: 
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableConfigurationProperties(MyProperties.class)
public class MyConfiguration {
}
Or use classpath scanning by adding @ConfigurationPropertiesScan to your main application class: 
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;

@SpringBootApplication
@ConfigurationPropertiesScan
public class MyApplication {
    // ...
}

​
Validating configuration

Combine @ConfigurationProperties with Bean Validation to catch configuration errors early at startup: 
import java.net.InetAddress;

import jakarta.validation.constraints.NotNull;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;

@ConfigurationProperties("my.service")
@Validated
public class MyProperties {

    @NotNull
    private InetAddress remoteAddress;

    // getters and setters ...

}
If my.service.remote-address is absent from the environment when the application starts, Spring Boot throws a BindValidationException immediately — before the application accepts any traffic.

​
JSON application properties

When OS environment variable naming restrictions prevent you from setting individual properties, encode a block of configuration as a single JSON string in SPRING_APPLICATION_JSON: 
$ SPRING_APPLICATION_JSON='{"my":{"name":"test"}}' java -jar myapp.jar
Or as a system property: 
$ java -Dspring.application.json='{"my":{"name":"test"}}' -jar myapp.jar
This results in my.name=test being added to the Environment.

​
Random values

Use RandomValuePropertySource to inject random values at startup, which is useful for secrets and test data: 
my:
  secret: "${random.value}"
  number: "${random.int}"
  bignumber: "${random.long}"
  uuid: "${random.uuid}"
  number-less-than-ten: "${random.int(10)}"
  number-in-range: "${random.int[1024,65536]}"

​
@Value vs @ConfigurationProperties

@Value@ConfigurationProperties
Binding styleSingle propertyWhole prefix group
Type coercionLimitedRich, including collections
ValidationManualBean Validation (@Validated)
Relaxed bindingPartialFull
IDE metadata supportNoYes (via annotation processor)
Best forSimple, one-off valuesStructured, multi-property config

Build docs developers (and LLMs) love

Get started for freeTalk to us