Spring Boot YAML to List of Objects: Collections & Nested Types Explained

Here's a story from last year: I was debugging a payment-processing microservice that suddenly started ignoring half the merchant configurations. We had a YAML list of 'acceptedPaymentMethods' — each with nested fields like 'methodName', 'feePercentage', and 'supportedCurrencies'. The YAML was perfectly valid, but Spring Boot was only loading the first two items. The rest were silently dropped. No errors, no warnings. Just lost revenue. That's the kind of problem you get when you assume YAML-to-object binding is trivial. It's not. Spring Boot's @ConfigurationProperties is powerful, but it has sharp edges — especially with lists, nested types, and immutable classes. In this tutorial, I'll show you exactly how to bind YAML lists to Java objects correctly, avoid the silent failures I've seen in production (including that payment processor), and handle edge cases like empty lists, null values, and deeply nested structures. You'll learn the official approach with Spring Boot 3.2+, but also the hard-won lessons from real incidents. By the end, you'll be able to model complex configuration hierarchies without fear, validate them at startup, and write tests that catch the subtle bugs that slip through code review.

Binding YAML Lists to Java Objects: The Basics

Spring Boot's @ConfigurationProperties is the idiomatic way to bind structured YAML to POJOs. For lists, the YAML list syntax (- item) maps directly to List<String>, List<Integer>, or lists of custom objects. Here's the hard truth: most teams get this wrong by using @Value with SpEL, which is brittle and doesn't support nested types. Instead, create a dedicated configuration class annotated with @ConfigurationProperties(prefix = "myapp"). For example, given a YAML like:

``yaml myapp: servers: - url: https://api.example.com timeout: 5000 - url: https://backup.example.com timeout: 10000 ``

You can bind it to:

``java @ConfigurationProperties(prefix = "myapp") public class AppProperties { private List<ServerConfig> servers = new ArrayList<>(); // getters and setters } ``

Where ServerConfig is a simple POJO with url and timeout. Enable this with @EnableConfigurationProperties(AppProperties.class) on a @Configuration class. The binding happens eagerly at startup; any mismatch in types (e.g., string where number expected) throws a ConversionFailedException. Always initialize collections to empty lists to avoid null pointers in production.

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

import java.util.ArrayList;
import java.util.List;

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

    private List<ServerConfig> servers = new ArrayList<>();

    public List<ServerConfig> getServers() {
        return servers;
    }

    public void setServers(List<ServerConfig> servers) {
        this.servers = servers;
    }

    public static class ServerConfig {
        private String url;
        private int timeout;

        public String getUrl() { return url; }
        public void setUrl(String url) { this.url = url; }
        public int getTimeout() { return timeout; }
        public void setTimeout(int timeout) { this.timeout = timeout; }

        @Override
        public String toString() {
            return "ServerConfig{url='" + url + "', timeout=" + timeout + "}";
        }
    }
}

What the Official Docs Won't Tell You

The official Spring Boot documentation glosses over several landmines. First: YAML lists of objects require mutable POJOs with public setters — no immutable record types unless you use constructor binding with @ConstructorBinding (Spring Boot 2.2+). If you use a record and forget @ConstructorBinding, you get a confusing BindingException at startup. Second: YAML merging with anchors (& and <<:) works in SnakeYAML, but Spring Boot's ConfigurationProperties binder does NOT support YAML anchors for list elements. I've seen teams try to DRY up configs with anchors only to find the binder silently skips the merged elements. Third: nested lists within lists (e.g., a list of objects each containing a list) require careful flattening — the binder expects a nested YAML structure, not a flat one. For example:

``yaml myapp: clusters: - name: prod nodes: - host: node1 - host: node2 ``

Binds to List<ClusterConfig> where ClusterConfig has List<NodeConfig> nodes. But if you write:

``yaml myapp: clusters: - name: prod - nodes: - host: node1 ``

That becomes two separate objects in the list — a bug that's hard to catch without integration tests. Finally: Spring Boot 3.x with SnakeYAML 2.0 changed how it handles duplicate keys — it now throws an exception by default instead of taking the last value. This broke many configs that had accidental duplicates.

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import java.util.ArrayList;
import java.util.List;

@Component
@ConfigurationProperties(prefix = "myapp")
public class ClusterConfig {

    private List<Cluster> clusters = new ArrayList<>();

    public List<Cluster> getClusters() { return clusters; }
    public void setClusters(List<Cluster> clusters) { this.clusters = clusters; }

    public static class Cluster {
        private String name;
        private List<Node> nodes = new ArrayList<>();

        public String getName() { return name; }
        public void setName(String name) { this.name = name; }
        public List<Node> getNodes() { return nodes; }
        public void setNodes(List<Node> nodes) { this.nodes = nodes; }
    }

    public static class Node {
        private String host;
        public String getHost() { return host; }
        public void setHost(String host) { this.host = host; }
    }
}

Binding Maps and Collections with Mixed Types

YAML supports maps (`key: value) and collections of maps. Spring Boot binds these to Map<String, Object> or Map<String, List<Something>>`. A common pattern is a list of maps — e.g., a list of feature flags with metadata:

``yaml myapp: features: - name: dark-mode enabled: true rollout: 50 - name: new-checkout enabled: false rollout: 0 ``

This binds to List<Map<String, Object>> if you don't define a POJO, but that's a code smell — you lose type safety. Instead, always define a POJO like FeatureFlag. For truly dynamic configs where keys are unknown at compile time, use Map<String, List<String>>. For example:

``yaml myapp: endpoint-groups: us-east: - https://east1.example.com - https://east2.example.com eu-west: - https://west1.example.com ``

Binds to Map<String, List<String>> endpointGroups. The key insight: YAML keys become map keys, and the list values become List<String>. Spring Boot handles type conversion automatically for primitives, strings, and enums. For custom types, you need a Converter bean. One gotcha: YAML treats null values as absent — if a key has a null value (e.g., key:), the map entry is excluded entirely. This can silently drop expected config entries. Always use @DefaultValue or set defaults in the POJO constructor for robustness.

For mixed collections (e.g., a list containing both strings and maps), YAML supports it but Java's type system doesn't without Object. Avoid this — it's a maintenance nightmare. Instead, use a wrapper POJO with a String type discriminator.

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import java.util.ArrayList;
import java.util.List;

@Component
@ConfigurationProperties(prefix = "myapp")
public class FeatureFlags {

    private List<FeatureFlag> features = new ArrayList<>();

    public List<FeatureFlag> getFeatures() { return features; }
    public void setFeatures(List<FeatureFlag> features) { this.features = features; }

    public static class FeatureFlag {
        private String name;
        private boolean enabled;
        private int rollout;

        public String getName() { return name; }
        public void setName(String name) { this.name = name; }
        public boolean isEnabled() { return enabled; }
        public void setEnabled(boolean enabled) { this.enabled = enabled; }
        public int getRollout() { return rollout; }
        public void setRollout(int rollout) { this.rollout = rollout; }
    }
}

Validation and Defaults for YAML-Listed Configurations

Production-grade applications must validate configuration at startup, not at first use. Spring Boot supports @Validated on @ConfigurationProperties classes with JSR-380 Bean Validation (e.g., @NotBlank, @Min, @NotEmpty). For lists, you can validate each element by annotating the list field with @Valid:

``java @Valid private List<@Valid ServerConfig> servers; ``

This triggers validation on each ServerConfig object. The @NotEmpty annotation on the list itself ensures at least one element exists. For defaults, initialize fields directly in the POJO — this is safer than relying on YAML defaults because Spring Boot merges defaults from multiple sources (e.g., application.yml, profile-specific files, environment variables). Environment variables override YAML lists in a non-intuitive way: a list in YAML can be replaced entirely by a comma-separated environment variable (e.g., MYAPP_SERVERS[0]_URL). This is fine for simple lists but breaks for nested objects — you'd need indexed properties in the env var name, which is error-prone.

Another pro tip: use @DurationUnit and @DataSizeUnit for timeouts and sizes in lists to avoid manual parsing. For example:

``yaml myapp: timeouts: - endpoint: /api duration: 5s ``

Binds to List<TimeoutConfig> with @DurationUnit(ChronoUnit.SECONDS) private Duration duration. This saves you from writing custom converters.

Finally, always add a @PostConstruct validation method in the configuration class to cross-validate list elements (e.g., no duplicate URLs, timeout ranges). This catches misconfigurations before the application accepts traffic.

import jakarta.validation.Valid;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotEmpty;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import org.springframework.validation.annotation.Validated;
import javax.annotation.PostConstruct;
import java.util.ArrayList;
import java.util.List;

@Component
@Validated
@ConfigurationProperties(prefix = "myapp")
public class ValidatedAppProperties {

    @NotEmpty(message = "At least one server must be configured")
    @Valid
    private List<ServerConfig> servers = new ArrayList<>();

    public List<ServerConfig> getServers() { return servers; }
    public void setServers(List<ServerConfig> servers) { this.servers = servers; }

    @PostConstruct
    public void validate() {
        long distinctUrls = servers.stream()
                .map(ServerConfig::getUrl)
                .distinct()
                .count();
        if (distinctUrls != servers.size()) {
            throw new IllegalStateException("Duplicate server URLs in configuration");
        }
    }

    public static class ServerConfig {
        @NotBlank(message = "URL must not be blank")
        private String url;
        @Min(value = 100, message = "Timeout must be at least 100ms")
        private int timeout;

        public String getUrl() { return url; }
        public void setUrl(String url) { this.url = url; }
        public int getTimeout() { return timeout; }
        public void setTimeout(int timeout) { this.timeout = timeout; }
    }
}

Advanced YAML Binding: Nested Maps and Collections of Complex Objects

Once you've mastered flat lists, the real power of YAML in Spring Boot emerges when dealing with nested structures. Let's say you're building a payment-processing system that needs to configure multiple gateways, each with its own set of endpoints and credentials. Here's the hard truth: most teams get this wrong by trying to force everything into a single flat properties file. Instead, use YAML's natural hierarchy. Define a top-level key like payment.gateways that maps to a list of objects. Each object can have nested maps for endpoints (e.g., sandbox, production) and even nested lists for retry strategies. For example, a Stripe gateway might have endpoints: {sandbox: "https://sandbox.stripe.com", production: "https://api.stripe.com"} and retry: [100, 200, 500] (milliseconds). Spring Boot's @ConfigurationProperties with a List<GatewayConfig> will bind this flawlessly, as long as your class has a List<GatewayConfig> field with getters/setters. The nested map becomes a Map<String, String> in Java, and the nested list becomes a List<Integer>. Use @Valid and @NotEmpty on fields to enforce constraints at startup. I've seen production outages because a missing endpoint caused a NullPointerException during runtime — validate early. The @ConstructorBinding (available since Spring Boot 2.2) is your friend for immutable objects; use it with @DefaultValue for optional fields. Remember: YAML's indentation is sacred — one wrong space and your entire binding fails silently.

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.ConstructorBinding;
import org.springframework.validation.annotation.Validated;
import javax.validation.constraints.NotEmpty;
import java.util.List;
import java.util.Map;

@Validated
@ConstructorBinding
@ConfigurationProperties(prefix = "payment")
public record GatewayConfig(
    @NotEmpty String name,
    Map<String, String> endpoints,
    List<Integer> retry,
    boolean enabled
) {}

// Application class must enable @EnableConfigurationProperties(GatewayConfig.class)

Binding YAML Lists to Polymorphic Types Using @JsonTypeInfo

Sometimes you need a list of objects that share a common interface but have different implementations. For example, in a SaaS billing system, you might have a list of DiscountStrategy objects: PercentageDiscount and FixedAmountDiscount. YAML can handle this using a discriminator field. Spring Boot's @ConfigurationProperties doesn't natively support polymorphism, but you can leverage Jackson's @JsonTypeInfo and @JsonSubTypes annotations on your interface. Here's the trick: Spring Boot uses Jackson internally for YAML binding (via SnakeYAML), so these annotations work seamlessly. Define an abstract class DiscountStrategy with @JsonTypeInfo(use = Id.NAME, property = "type") and @JsonSubTypes({@Type(value = PercentageDiscount.class, name = "percentage"), @Type(value = FixedAmountDiscount.class, name = "fixed")}). Then in your YAML, each object in the list must have a type field: - type: percentage, rate: 0.1. Spring Boot will instantiate the correct subclass. I've used this in production for feature flags with different implementation strategies. The gotcha: the property name in @JsonTypeInfo must match exactly the key in your YAML. Misspelling type as typo will silently create a generic LinkedHashMap instead of your subclass. Always add a test that loads the configuration and checks the actual runtime type. Since Spring Boot 2.2, you can also use @ConfigurationProperties on a @Bean method if you need more control, but for most cases, the Jackson approach is cleaner. Remember that this only works for @ConfigurationProperties binding, not for @Value injection.

import com.fasterxml.jackson.annotation.JsonSubTypes;
import com.fasterxml.jackson.annotation.JsonTypeInfo;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import java.util.List;

@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type")
@JsonSubTypes({
    @JsonSubTypes.Type(value = PercentageDiscount.class, name = "percentage"),
    @JsonSubTypes.Type(value = FixedAmountDiscount.class, name = "fixed")
})
public sealed interface DiscountStrategy permits PercentageDiscount, FixedAmountDiscount {
    double apply(double amount);
}

@Component
@ConfigurationProperties(prefix = "billing")
public class BillingConfig {
    private List<DiscountStrategy> discounts;
    // getters and setters
}

// YAML: billing.discounts[0].type=percentage, billing.discounts[0].rate=0.1

Default Values and Optional Fields in Nested YAML Lists

Not every field in your YAML list needs to be specified. Spring Boot provides several ways to handle defaults. For primitive types like int and boolean, you can set default values directly in your Java class: private int timeout = 5000;. For String fields, use private String name = "default";. But what about nested objects? If a YAML list entry omits a nested map, you get null. To avoid NPEs, initialize the field: private Map<String, String> metadata = new HashMap<>();. For lists of objects, if you omit the entire list, you get null — so initialize with List.of() if an empty list is acceptable. Since Spring Boot 2.2, @DefaultValue annotation on constructor parameters provides defaults for immutable objects. For example, @DefaultValue("5000") int timeout. The value must be a string; Spring converts it. One common mistake: assuming that YAML's null or empty value will be overridden by a default. Actually, YAML's ~ (null) or missing key will leave the field as its Java default (e.g., null for objects, 0 for ints). If you want a non-null default, you must set it in Java. Also, beware of YAML's true, false, yes, no parsing for booleans. Spring Boot's relaxed binding will convert yes to true, but enabled: yes works. However, for consistency, always use true/false. In a production monitoring system, I saw a configuration where retryEnabled: on was interpreted as true due to YAML's boolean handling, but on is not a standard Spring Boot boolean value — it worked by accident. Stick to true/false to avoid confusion. For nested lists of complex objects, if an entry has missing fields, Spring Boot will create the object with null fields unless defaults are specified. Use @Builder with @DefaultValue for a clean approach.

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.ConstructorBinding;
import org.springframework.boot.context.properties.bind.DefaultValue;
import java.util.List;

@ConstructorBinding
@ConfigurationProperties(prefix = "services")
public record ServiceConfig(
    String name,
    @DefaultValue("3000") int timeout,
    @DefaultValue("true") boolean retryEnabled,
    List<String> tags
) {
    // YAML: services[0].name=api, services[0].timeout=5000
    // YAML: services[1].name=db (timeout defaults to 3000, retryEnabled defaults to true)
}

// Application must have @EnableConfigurationProperties(ServiceConfig.class)

Debugging YAML Binding: Common Failures and How to Fix Them

YAML binding failures are notoriously silent. You might define a list of objects in YAML, but Spring Boot silently ignores it if the structure doesn't match. Here's my go-to debugging checklist. First, enable debug logging: logging.level.org.springframework.boot.context.properties=DEBUG. This will show you exactly what Spring Boot is trying to bind. Second, use the @ConfigurationPropertiesScan annotation (Spring Boot 2.2+) to automatically detect @ConfigurationProperties beans without manual @EnableConfigurationProperties. Third, check your YAML indentation: every nested level must be exactly 2 spaces. A common mistake is mixing spaces and tabs. Fourth, verify that your Java class has appropriate getters and setters (or is a record). Spring Boot uses setter injection by default; if you use @ConstructorBinding, ensure the constructor is public and parameters match the YAML keys. Fifth, for lists, the YAML syntax must be either list: [item1, item2] (inline) or list: - item1 - item2 (block). Mixing both in the same file can cause issues. Sixth, check for key naming: Spring Boot's relaxed binding (e.g., my-prop, myProp, MY_PROP) is forgiving, but for lists, the keys must match exactly. If your YAML has my-list[0].name, the Java field must be myList (a List<Something>). The [0] index is automatically handled. Seventh, if you're using @Validated with @NotEmpty on a list, Spring Boot will throw a BindException at startup if the list is empty. This is a good practice. Finally, use the spring-boot-configuration-processor dependency to generate metadata for your custom properties, which gives you auto-completion in IDEs and helps catch typos. In a recent project, a colleague spent 2 hours debugging a list that never populated — turns out the YAML file had a BOM (Byte Order Mark) from a Windows editor. Use a linter like yamllint to catch these issues before runtime.

logging:
  level:
    org.springframework.boot.context.properties: DEBUG

payment:
  gateways:
    - name: "stripe"
      endpoints:
        sandbox: "https://sandbox.stripe.com"
        production: "https://api.stripe.com"
      retry:
        - 100
        - 200
        - 500
      enabled: true