Spring Boot Properties Prefix Must Be in Canonical Form

1. Overview

In this quick tutorial, we’re going to take a close look at the Spring Boot error “Reason: Canonical names should be kebab-case (‘-‘ separated), lowercase alpha-numeric characters, and must start with a letter“.

First of all, we’re going to shed light on the main cause of this error in Spring Boot. Then, we’ll dive into how to reproduce and solve it using a practical example.

2. Problem Statement

First, let’s understand what the error message means. “Canonical names should be kebab-case” simply tells us that Canonical names (Canonical names refer to the property names that uniquely identify a property) should be kebab cases.

To ensure consistency, the naming convention used in the prefix parameter of the @ConfigurationProperties annotation should follow the kebab casing.

For example:

@ConfigurationProperties(prefix = "my-example")

3. Maven Dependencies

Since this is a Maven-based project, let’s add the necessary dependencies to the pom.xml:

<dependency> 
    <groupId>org.springframework.boot</groupId> 
    <artifactId>spring-boot-starter</artifactId> 
    <version>3.0.5</version>
</dependency>

For reproducing the issue, the spring-boot-starter is the one and only dependency that is needed.

4. Reproducing the Error

4.1. Application Configuration

@Configuration
@ConfigurationProperties(prefix = "customProperties")
public class MainConfiguration {
    String name;
 
    // getters and setters
}

Then, we need to add a custom property to the application.properties file:

custom-properties.name="Baeldung"

The application.properties are located under src/main/resources:

|   pom.xml
+---src
|   +---main
|   |   +---java
|   |   |   \---com
|   |   |       \---baeldung
|   |   |           ...
|   |   |           ...
|   |   \---resources
|   |           application.properties

Now, let’s run our sample Spring Boot application by executing the mvn spring-boot:run command in our project root folder and see what happens:

$ mvn spring-boot:run
...
...
***************************
APPLICATION FAILED TO START
***************************

Description:

Configuration property name 'customProperties' is not valid:

    Invalid characters: 'P'
    Bean: mainConfiguration
    Reason: Canonical names should be kebab-case ('-' separated), lowercase alpha-numeric characters and must start with a letter

Action:

Modify 'customProperties' so that it conforms to the canonical names requirements.

As shown above, we get an error message Modify ‘customProperties’ so that it conforms to the canonical names requirements. This error message is indicating that the current naming convention used for customProperties does not follow the naming conventions set by Spring. In other words, the name customProperties needs to be changed to adhere to the requirements for naming properties in Spring.

5. Fixing the Error

We need to change the property prefix from:

@ConfigurationProperties(prefix = "customProperties")

To a kebab case prefix:

@ConfigurationProperties(prefix = "custom-properties")

While in the properties, we can keep any styling, and we will be good to access them.

6. Advantage of Kebab Casing

The main advantage of using the kebab casing while accessing those properties is that we can use any of the below casings:

• camelCaseLikeThis
• PascalCaseLikeThis
• snake_case_like_this
• kebab-case-like-this

in the properties file and access them using the kebab casing.

@ConfigurationProperties(prefix = "custom-properties")

will be able to access any of the below properties

customProperties.name="Baeldung"

CustomProperties.name="Baeldung"

custom_properties.name="Baeldung"

custom-properties.name="Baeldung"

7. Conclusion

In this tutorial, we understood that Spring Boot supports multiple formats, including camel case, snake case, and kebab case in property names but encourages us to access them canonically in kebab casing, thus reducing the likelihood of errors or confusion caused by inconsistent naming conventions.