Appendix B. Configuration meta-data

Appendix B. Configuration meta-data
Prev	Part IX. Appendices	Next

Spring Boot jars are shipped with meta-data files that provide details of all supported configuration properties. The files are designed to allow IDE developers to offer contextual help and “code completion” as users are working with application.properties or application.yml files.

The majority of the meta-data file is generated automatically at compile time by processing all items annotated with @ConfigurationProperties.

B.1 Meta-data format

Configuration meta-data files are located inside jars under META-INF/spring-configuration-metadata.json They use a simple JSON format with items categorized under either “groups” or “properties”:

{"groups": [
    {
        "name": "server",
        "type": "org.springframework.boot.autoconfigure.web.ServerProperties",
        "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
    }
    ...
],"properties": [
    {
        "name": "server.port",
        "type": "java.lang.Integer",
        "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
    },
    {
        "name": "server.servlet-path",
        "type": "java.lang.String",
        "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
        "defaultValue": "/"
    }
    ...
]}

Each “property” is a configuration item that the user specifies with a given value. For example server.port and server.servlet-path might be specified in application.properties as follows:

server.port=9090
server.servlet-path=/home

The “groups” are higher level items that don’t themselves specify a value, but instead provide a contextual grouping for properties. For example the server.port and server.servlet-path properties are part of the server group.

	Note
	It is not required that every “property” has a “group”, some properties might just exist in their own right.

B.1.1 Group Attributes

The JSON object contained in the groups array can contain the following attributes:

Name	Type	Purpose
`name`	String	The full name of the group. This attribute is mandatory.
`type`	String	The class name of the data type of the group. For example, if the group was based on a class annotated with `@ConfigurationProperties` the attribute would contain the fully qualified name of that class. If it was based on a `@Bean` method, it would be the return type of that method. The attribute may be omitted if the type is not known.
`description`	String	A short description of the group that can be displayed to users. May be omitted if no description is available. It is recommended that descriptions are a short paragraphs, with the first line providing a concise summary. The last line in the description should end with a period (`.`).
`sourceType`	String	The class name of the source that contributed this group. For example, if the group was based on a `@Bean` method annotated with `@ConfigurationProperties` this attribute would contain the fully qualified name of the `@Configuration` class containing the method. The attribute may be omitted if the source type is not known.
`sourceMethod`	String	The full name of the method (include parenthesis and argument types) that contributed this group. For example, the name of a `@ConfigurationProperties` annotated `@Bean` method. May be omitted if the source method is not known.

B.1.2 Property Attributes

The JSON object contained in the properties array can contain the following attributes:

Name	Type	Purpose
`name`	String	The full name of the property. Names are in lowercase dashed form (e.g. `server.servlet-path`). This attribute is mandatory.
`type`	String	The class name of the data type of the property. For example, `java.lang.String`. This attribute can be used to guide the user as to the types of values that they can enter. For consistency, the type of a primitive is specified using its wrapper counterpart, i.e. `boolean` becomes `java.lang.Boolean`. Note that this class may be a complex type that gets converted from a String as values are bound. May be omitted if the type is not known.
`description`	String	A short description of the group that can be displayed to users. May be omitted if no description is available. It is recommended that descriptions are a short paragraphs, with the first line providing a concise summary. The last line in the description should end with a period (`.`).
`sourceType`	String	The class name of the source that contributed this property. For example, if the property was from a class annotated with `@ConfigurationProperties` this attribute would contain the fully qualified name of that class. May be omitted if the source type is not known.
`defaultValue`	Object	The default value which will be used if the property is not specified. Can also be an array of value(s) if the type of the property is an array. May be omitted if the default value is not known.
`deprecated`	boolean	Specify if the property is deprecated. May be omitted if the field is not deprecated or if that information is not known.

B.1.3 Repeated meta-data items

It is perfectly acceptable for “property” and “group” objects with the same name to appear multiple times within a meta-data file. For example, Spring Boot binds spring.datasource properties to Hikari, Tomcat and DBCP classes, with each potentially offering overlap of property names. Consumers of meta-data should take care to ensure that they support such scenarios.

B.2 Generating your own meta-data using the annotation processor

You can easily generate your own configuration meta-data file from items annotated with @ConfigurationProperties by using the spring-boot-configuration-processor jar. The jar includes a Java annotation processor which is invoked as your project is compiled. To use the processor, simply include spring-boot-configuration-processor as an optional dependency, for example with Maven you would add:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>

With Gradle, you can use the propdeps-plugin and specify:

	dependencies {
		optional "org.springframework.boot:spring-boot-configuration-processor"
	}

	compileJava.dependsOn(processResources)
}

	Note
	You need to add `compileJava.dependsOn(processResources)` to your build to ensure that resources are processed before code is compiled. Without this directive any `additional-spring-configuration-metadata.json` files will not be processed.

The processor will pickup both classes and methods that are annotated with @ConfigurationProperties. The Javadoc for field values within configuration classes will be used to populate the description attribute.

	Note
	You should only use simple text with `@ConfigurationProperties` field Javadoc since they are not processed before being added to the JSON.

Properties are discovered via the presence of standard getters and setters with special handling for collection types (that will be detected even if only a getter is present). The annotation processor also supports the use of the @Data, @Getter and @Setter lombok annotations.

B.2.1 Nested properties

The annotation processor will automatically consider inner classes as nested properties. For example, the following class:

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

    private String name;

    private Host host;

    // ... getter and setters

    private static class Host {

        private String ip;

        private int port;

        // ... getter and setters

    }

}

Will produce meta-data information for server.name, server.host.ip and server.host.port properties. You can use the @NestedConfigurationProperty annotation on a field to indicate that a regular (non-inner) class should be treated as if it were nested.

B.2.2 Adding additional meta-data

Spring Boot’s configuration file handling is quite flexible; and it often the case that properties may exist that are not bound to a @ConfigurationProperties bean. To support such cases, the annotation processor will automatically merge items from META-INF/additional-spring-configuration-metadata.json into the main meta-data file.

The format of the additional-spring-configuration-metadata.json file is exactly the same as the regular spring-configuration-metadata.json. The additional properties file is optional, if you don’t have any additional properties, simply don’t add it.

Prev	Up	Next
Appendix A. Common application properties	Home	Appendix C. Auto-configuration classes