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")
In the above code snippet, the prefix my-example should adhere to the kebab casing convention.
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
Let’s register the required component:
@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.
As usual, the complete code for this article is available on GitHub.
