One Annotation to Elegantly Bind Custom Objects in Spring Boot

Environment

Spring Boot 3.5.0

1. Introduction

@ConfigurationProperties is the annotation used by Spring Boot to bind configuration properties (e.g., application.yml) to Java objects. It supports nested objects, collections, and type‑safe validation.

When Spring Boot binds a @ConfigurationProperties bean, it attempts to convert external property values to the target type. If no suitable converter exists, an exception is thrown.

@Component
@ConfigurationProperties(prefix = "pack.app")
public class AppProperties {
  private String title;
  private String version;
  private Author author;
  public static class Author {
    private String name;
    private String email;
  }
}

Corresponding YAML configuration:

pack:
  app:
    title: XXXOOO
    version: 1.0.0
    author: pack_xg,[email protected]

Because the author property is a single string, Spring cannot convert it to the Author type and throws an error (no String‑to‑Author converter).

2. Practical Cases

2.1 Custom ConversionService

Define a Converter implementation that parses the comma‑separated string and creates an Author instance.

public class StringToAuthorConvert implements Converter<String, Author> {
  @Override
  public Author convert(String source) {
    if (!StringUtils.hasLength(source)) {
      return null;
    }
    String[] values = source.split(",");
    if (values.length != 2) {
      return null;
    }
    return new Author(values[0], values[1]);
  }
}

Register the converter in a ConversionService bean named conversionService:

@Bean
ConversionService conversionService() {
  FormattingConversionService cs = new FormattingConversionService();
  cs.addConverter(new StringToAuthorConvert());
  return cs;
}

Result:

AppProperties [title=XXXOOO, version=1.0.0, author=Author [name=pack_xg, [email protected]]]

2.2 Custom PropertyEditor

Implement a PropertyEditorSupport subclass to perform the same parsing.

public class AuthorPropertyEditor extends PropertyEditorSupport {
  @Override
  public void setAsText(String text) throws IllegalArgumentException {
    if (StringUtils.hasLength(text)) {
      String[] values = text.split(",");
      if (values.length == 2) {
        setValue(new Author(values[0] + "@", values[1]));
      }
    }
  }
}

Register it via CustomEditorConfigurer:

@Bean
CustomEditorConfigurer customEditorConfigurer() {
  CustomEditorConfigurer configurer = new CustomEditorConfigurer();
  configurer.setCustomEditors(Map.of(Author.class, AuthorPropertyEditor.class));
  return configurer;
}

Result (note the added “@” suffix in the name field):

AppProperties [title=XXXOOO, version=1.0.0, author=Author [name=pack_xg@, [email protected]]]

2.3 Using @ConfigurationPropertiesBinding

The simplest approach is to annotate the Converter bean with @ConfigurationPropertiesBinding, allowing Spring Boot to pick it up automatically.

@Component
@ConfigurationPropertiesBinding
public class StringToAuthorConvert implements Converter<String, Author> {
  // same convert method as in 2.1
}

@ConfigurationPropertiesBinding

can be applied not only to Converter beans but also to other conversion‑related types such as Printer, Parser, Formatter, ConverterFactory, and GenericConverter.

Printer

Parser

Formatter

Converter

ConverterFactory

GenericConverter