Introduction

Using multiple YAML files in Spring Boot is the normal way to separate shared defaults from environment-specific settings and feature-specific configuration. The important part is understanding which mechanism you are using: profile-specific files, multi-document YAML, or explicit imports with the config-data system.

Start with application.yml and Profile Files

Spring Boot always loads application.yml as the baseline configuration. Then it overlays profile-specific files such as application-dev.yml or application-prod.yml when those profiles are active.

A common layout looks like this:

1src/main/resources/
2  application.yml
3  application-dev.yml
4  application-prod.yml

Base settings:

1server:
2  port: 8080
3
4app:
5  feature-x-enabled: false
6  pool-size: 10

Development overrides:

1app:
2  feature-x-enabled: true
3  pool-size: 5
4
5logging:
6  level:
7    root: DEBUG

Production overrides:

1app:
2  pool-size: 30
3
4logging:
5  level:
6    root: INFO

The rule is simple: keep the shared defaults in application.yml, then override only the differences in profile files.

Activate Profiles Explicitly

Profile-specific files do nothing until the profile is active. You can activate profiles from the command line, environment, or tests.

Command-line activation:

java -jar app.jar --spring.profiles.active=dev

Environment variable activation:

export SPRING_PROFILES_ACTIVE=prod

Test activation:

1import org.junit.jupiter.api.Test;
2import org.springframework.boot.test.context.SpringBootTest;
3import org.springframework.test.context.ActiveProfiles;
4
5@SpringBootTest
6@ActiveProfiles("dev")
7class ConfigLoadTest {
8    @Test
9    void contextLoads() {
10    }
11}

Being explicit matters in CI and deployment manifests. If you rely on defaults accidentally, you can end up running production code with development settings.

Split by Concern with spring.config.import

When configuration grows, profile files are not always enough. Spring Boot also supports importing additional config files:

1spring:
2  config:
3    import:
4      - classpath:config/datasource.yml
5      - classpath:config/cache.yml
6
7app:
8  name: order-service

An imported file might hold database settings:

1spring:
2  datasource:
3    url: jdbc:postgresql://localhost:5432/orders
4    username: orders_user
5    password: ${DB_PASSWORD:local-password}

And another might hold cache settings:

spring:
  cache:
    type: caffeine

This pattern is useful when different teams own different sections of configuration or when one massive YAML file has become difficult to review safely.

Multi-Document YAML Is Another Option

If you prefer a single physical file, YAML supports multiple documents separated by ---. Spring Boot can activate documents conditionally:

1app:
2  feature-x-enabled: false
3---
4spring:
5  config:
6    activate:
7      on-profile: dev
8app:
9  feature-x-enabled: true

This is handy for small services where you want profile-specific settings without creating many separate files. It becomes harder to navigate once the configuration grows large, so use it selectively.

Bind Configuration to Typed Classes

Multiple YAML files are easier to manage when the properties bind into a typed class instead of being fetched ad hoc from the environment:

1import org.springframework.boot.context.properties.ConfigurationProperties;
2
3@ConfigurationProperties(prefix = "app")
4public class AppProperties {
5    private boolean featureXEnabled;
6    private int poolSize;
7
8    public boolean isFeatureXEnabled() {
9        return featureXEnabled;
10    }
11
12    public void setFeatureXEnabled(boolean featureXEnabled) {
13        this.featureXEnabled = featureXEnabled;
14    }
15
16    public int getPoolSize() {
17        return poolSize;
18    }
19
20    public void setPoolSize(int poolSize) {
21        this.poolSize = poolSize;
22    }
23}

Then enable scanning:

1import org.springframework.boot.autoconfigure.SpringBootApplication;
2import org.springframework.boot.context.properties.ConfigurationPropertiesScan;
3
4@SpringBootApplication
5@ConfigurationPropertiesScan
6public class DemoApplication {
7}

Typed binding helps catch invalid values earlier and makes configuration usage easier to test.

Know What Overrides What

Property precedence matters whenever the same key appears in multiple places. Environment variables and command-line arguments usually override packaged YAML values. Profile-specific files also override the baseline file for matching keys.

For critical settings, log the effective values at startup:

1import org.springframework.boot.CommandLineRunner;
2import org.springframework.core.env.Environment;
3import org.springframework.stereotype.Component;
4
5@Component
6class StartupConfigLog implements CommandLineRunner {
7    private final Environment environment;
8
9    StartupConfigLog(Environment environment) {
10        this.environment = environment;
11    }
12
13    @Override
14    public void run(String... args) {
15        System.out.println(String.join(",", environment.getActiveProfiles()));
16        System.out.println(environment.getProperty("server.port"));
17    }
18}

That small diagnostic step saves time when you are unsure which file actually won.

Common Pitfalls

• Putting every environment value in one file and then duplicating almost the whole file for each profile.
• Forgetting to activate the intended profile and assuming application-dev.yml or application-prod.yml is being used.
• Mixing older configuration patterns with current config-data imports without understanding precedence.
• Storing real production secrets directly in repository YAML files instead of external secret sources.
• Reading many individual properties manually instead of binding them into typed configuration classes.

Summary

• Use application.yml for shared defaults and profile files for environment-specific overrides.
• Activate profiles explicitly in local runs, tests, and deployments.
• Use spring.config.import when you want separate YAML files by concern.
• Consider multi-document YAML for small cases, but keep readability in mind.
• Bind configuration into typed classes so multi-file setups stay maintainable.