Spring Top

I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2:


1. Overview

In this quick tutorial, we're going to take a close look at how to inject a map from a YAML file in Spring Boot.

First, we'll start with a little bit of insight on YAML files in Spring Framework. Then, we'll showcase, through a practical example, how to bind YAML properties to a Map.

2. YAML Files in Spring Framework

Using YAML files to store external configuration data is a common practice among Spring developers. Basically, Spring supports YAML documents as an alternative to properties and uses SnakeYAML under the hood to parse them.

Without further ado, let’s see what a typical YAML file looks like:

  port: 8090
    name: myapplication
    url: http://myapplication.com

As we can see, the YAML file is self-explanatory and more human-readable. As a matter of fact, YAML provides a fancy and concise way to store hierarchical configuration data.

By default, Spring Boot reads configuration properties from application.properties or application.yml at application startup. However, we can use @PropertySource to load a custom YAML file.

Now that we are familiar with what a YAML file is, let's see how to inject YAML properties as a Map in Spring Boot.

3. How to Inject a Map from a YAML File

Spring Boot has taken data externalization to the next level by providing a handy annotation called @ConfigurationProperties. This annotation is introduced to easily inject external properties from configuration files directly into Java objects.

In this section, we're going to cover in-depth how to bind YAML properties into a bean class using the @ConfigurationProperties annotation.

First, let's define some key-value properties in application.yml:

    name: InjectMapFromYAML
    url: http://injectmapfromyaml.dev
    description: How To Inject a map from a YAML File in Spring Boot
      - /dev/root
      - /dev/md2
      - /dev/md4
      username: root
      password: rootpass
      username: guest
      password: guestpass

In this example, we'll try to map application into a simple Map<String, String>. Similarly, we'll inject config details as a Map<String, List<String>>, and users as a Map with String keys and objects belonging to a user-defined class – Credential – as values.

Second, let's create a bean class – ServerProperties – to encapsulate the logic of binding our configuration properties to Maps:

@ConfigurationProperties(prefix = "server")
public class ServerProperties {

    private Map<String, String> application;
    private Map<String, List<String>> config;
    private Map<String, Credential> users;

    // getters and setters

    public class Credential {
        private String username;
        private String password;
        // getters and setters

As we can see, we decorated the ServerProperties class with @ConfigurationProperties. That way, we tell Spring to map all the properties with the specified prefix to an object of ServerProperties.

Recall that our app needs to be enabled for configuration properties as well, though this is done automatically in most Spring Boot applications.

Finally, let's test if our YAML properties are properly injected as Maps:

class MapFromYamlIntegrationTest {

    private ServerProperties serverProperties;

    public void whenYamlFileProvidedThenInjectSimpleMap() {
          .containsOnlyKeys("name", "url", "description");


    public void whenYamlFileProvidedThenInjectComplexMap() {




4. @ConfigurationProperties vs @Value

Now let's do a quick comparison of @ConfigurationProperties and @Value.

Despite the fact that both annotations can be used to inject properties from configuration files, they are quite different. The major difference between these two annotations is that each one serves a different purpose.

In short, @Value allows us to inject directly a particular property value by its key. However, @ConfigurationProperties annotation binds multiple properties to a particular object and provides access to the properties through the mapped object.

In general, Spring recommends using @ConfigurationProperties over @Value when it comes to injecting configuration data. @ConfigurationProperties offers a great way to centralize and group configuration properties in a structured object that we can inject later into other beans.

5. Conclusion

To sum it up, we first explained how to inject a Map from a YAML file in Spring Boot. Then, we highlighted the difference between @ConfigurationProperties and @Value.

As usual, the complete source code for the article is available over on GitHub.

Spring bottom

I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2:

Inline Feedbacks
View all comments