Appendix B. Configuration Metadata (2023)

AppendixB.Configuration Metadata

Spring Boot jars include metadata files that provide details of all supportedconfiguration properties. The files are designed to let IDE developers offercontextual help and “code completion” as users are working with application.propertiesor application.yml files.

The majority of the metadata file is generated automatically at compile time byprocessing all items annotated with @ConfigurationProperties. However, it is possibleto write part of the metadata manuallyfor corner cases or more advanced use cases.

B.1Metadata Format

Configuration metadata files are located inside jars underMETA-INF/spring-configuration-metadata.json They use a simple JSON format with itemscategorized under either “groups” or “properties” and additional values hintscategorized under "hints", as shown in the following example:

{"groups": [{"name": "server","type": "org.springframework.boot.autoconfigure.web.ServerProperties","sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"},{"name": "spring.jpa.hibernate","type": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate","sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties","sourceMethod": "getHibernate()"}...],"properties": [{"name": "server.port","type": "java.lang.Integer","sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"},{"name": "server.address","type": "java.net.InetAddress","sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"},{ "name": "spring.jpa.hibernate.ddl-auto", "type": "java.lang.String", "description": "DDL mode. This is actually a shortcut for the \"hibernate.hbm2ddl.auto\" property.", "sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate"}...],"hints": [{"name": "spring.jpa.hibernate.ddl-auto","values": [{"value": "none","description": "Disable DDL handling."},{"value": "validate","description": "Validate the schema, make no changes to the database."},{"value": "update","description": "Update the schema if necessary."},{"value": "create","description": "Create the schema and destroy previous data."},{"value": "create-drop","description": "Create and then destroy the schema at the end of the session."}]}]}

Each “property” is a configuration item that the user specifies with a given value.For example, server.port and server.address might be specified inapplication.properties, as follows:

server.port=9090server.address=127.0.0.1

The “groups” are higher level items that do not themselves specify a value but insteadprovide a contextual grouping for properties. For example, the server.port andserver.address properties are part of the server group.

	Note
	It is not required that every “property” has a “group”. Some properties mightexist in their own right.

Finally, “hints” are additional information used to assist the user in configuring agiven property. For example, when a developer is configuring thespring.jpa.hibernate.ddl-auto property, a tool can use the hints to offer someauto-completion help for the none, validate, update, create, and create-dropvalues.

B.1.1Group Attributes

The JSON object contained in the groups array can contain the attributes shown in thefollowing table:

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 were based on a class annotated with `@ConfigurationProperties`, the attribute would contain the fully qualified name of that class. If it were based on a `@Bean` method, it would be the return type of that method. If the type is not known, the attribute may be omitted.
`description`	String	A short description of the group that can be displayed to users. If not description is available, it may be omitted. It is recommended that descriptions be 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 were based on a `@Bean` method annotated with `@ConfigurationProperties`, this attribute would contain the fully qualified name of the `@Configuration` class that contains the method. If the source type is not known, the attribute may be omitted.
`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). If the source method is not known, it may be omitted.

B.1.2Property Attributes

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

Name	Type	Purpose
`name`	String	The full name of the property. Names are in lower-case period-separated form (for example, `server.address`). This attribute is mandatory.
`type`	String	The full signature of the data type of the property (for example, `java.lang.String`) but also a full generic type (such as `java.util.Map<java.util.String,acme.MyEnum>`). You can use this attribute to guide the user as to the types of values that they can enter. For consistency, the type of a primitive is specified by using its wrapper counterpart (for example, `boolean` becomes `java.lang.Boolean`). Note that this class may be a complex type that gets converted from a `String` as values are bound. If the type is not known, it may be omitted.
`description`	String	A short description of the group that can be displayed to users. If no description is available, it may be omitted. It is recommended that descriptions be 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 were from a class annotated with `@ConfigurationProperties`, this attribute would contain the fully qualified name of that class. If the source type is unknown, it may be omitted.
`defaultValue`	Object	The default value, which is used if the property is not specified. If the type of the property is an array, it can be an array of value(s). If the default value is unknown, it may be omitted.
`deprecation`	Deprecation	Specify whether the property is deprecated. If the field is not deprecated or if that information is not known, it may be omitted. The next table offers more detail about the `deprecation` attribute.

The JSON object contained in the deprecation attribute of each properties element cancontain the following attributes:

Name	Type	Purpose
`level`	String	The level of deprecation, which can be either `warning` (the default) or `error`. When a property has a `warning` deprecation level, it should still be bound in the environment. However, when it has an `error` deprecation level, the property is no longer managed and is not bound.
`reason`	String	A short description of the reason why the property was deprecated. If no reason is available, it may be omitted. It is recommended that descriptions be short paragraphs, with the first line providing a concise summary. The last line in the description should end with a period (`.`).
`replacement`	String	The full name of the property that replaces this deprecated property. If there is no replacement for this property, it may be omitted.

	Note
	Prior to Spring Boot 1.3, a single `deprecated` boolean attribute can be usedinstead of the `deprecation` element. This is still supported in a deprecated fashion andshould no longer be used. If no reason and replacement are available, an empty`deprecation` object should be set.

Deprecation can also be specified declaratively in code by adding the@DeprecatedConfigurationProperty annotation to the getter exposing the deprecatedproperty. For instance, assume that the app.acme.target property was confusing andwas renamed to app.acme.name. The following example shows how to handle that situation:

@ConfigurationProperties("app.acme")public class AcmeProperties {private String name;public String getName() { ... }public void setName(String name) { ... }@DeprecatedConfigurationProperty(replacement = "app.acme.name")@Deprecatedpublic String getTarget() {return getName();}@Deprecatedpublic void setTarget(String target) {setName(target);}}

	Note
	There is no way to set a `level`. `warning` is always assumed, since code is stillhandling the property.

The preceding code makes sure that the deprecated property still works (delegatingto the name property behind the scenes). Once the getTarget and setTargetmethods can be removed from your public API, the automatic deprecation hint in themetadata goes away as well. If you want to keep a hint, adding manual metadata withan error deprecation level ensures that users are still informed about that property.Doing so is particularly useful when a replacement is provided.

B.1.3Hint Attributes

The JSON object contained in the hints array can contain the attributes shown in thefollowing table:

Name	Type	Purpose
`name`	String	The full name of the property to which this hint refers. Names are in lower-case period-separated form (such as `spring.mvc.servlet.path`). If the property refers to a map (such as `system.contexts`), the hint either applies to the keys of the map (`system.context.keys`) or the values (`system.context.values`) of the map. This attribute is mandatory.
`values`	ValueHint[]	A list of valid values as defined by the `ValueHint` object (described in the next table). Each entry defines the value and may have a description.
`providers`	ValueProvider[]	A list of providers as defined by the `ValueProvider` object (described later in this document). Each entry defines the name of the provider and its parameters, if any.

Name	Type	Purpose
`value`	Object	A valid value for the element to which the hint refers. If the type of the property is an array, it can also be an array of value(s). This attribute is mandatory.
`description`	String	A short description of the value that can be displayed to users. If no description is available, it may be omitted . It is recommended that descriptions be short paragraphs, with the first line providing a concise summary. The last line in the description should end with a period (`.`).

Name	Type	Purpose
`name`	String	The name of the provider to use to offer additional content assistance for the element to which the hint refers.
`parameters`	JSON object	Any additional parameter that the provider supports (check the documentation of the provider for more details).

B.1.4Repeated Metadata Items

Objects with the same “property” and “group” name can appear multiple times within ametadata file. For example, you could bind two separate classes to the same prefix, witheach having potentially overlapping property names. While the same names appearing in themetadata multiple times should not be common, consumers of metadata should take care toensure that they support it.

B.2Providing Manual Hints

To improve the user experience and further assist the user in configuring a givenproperty, you can provide additional metadata that:

Describes the list of potential values for a property.
Associates a provider, to attach a well defined semantic to a property, so that a toolcan discover the list of potential values based on the project’s context.

B.2.1Value Hint

The name attribute of each hint refers to the name of a property. In theinitial example shown earlier, we provide five valuesfor the spring.jpa.hibernate.ddl-auto property: none, validate, update, create,and create-drop. Each value may have a description as well.

If your property is of type Map, you can provide hints for both the keys and thevalues (but not for the map itself). The special .keys and .values suffixes mustrefer to the keys and the values, respectively.

Assume a sample.contexts maps magic String values to an integer, as shown in thefollowing example:

@ConfigurationProperties("sample")public class SampleProperties {private Map<String,Integer> contexts;// getters and setters}

The magic values are (in this example) are sample1 and sample2. In order to offeradditional content assistance for the keys, you could add the following JSON tothe manual metadata of the module:

{"hints": [{"name": "sample.contexts.keys","values": [{"value": "sample1"},{"value": "sample2"}]}]}

	Tip
	We recommend that you use an `Enum` for those two values instead. If your IDEsupports it, this is by far the most effective approach to auto-completion.

B.2.2Value Providers

Providers are a powerful way to attach semantics to a property. In this section, wedefine the official providers that you can use for your own hints. However, your favoriteIDE may implement some of these or none of them. Also, it could eventually provide itsown.

	Note
	As this is a new feature, IDE vendors must catch up with how it works. Adoptiontimes naturally vary.

The following table summarizes the list of supported providers:

Name	Description
`any`	Permits any additional value to be provided.
`class-reference`	Auto-completes the classes available in the project. Usually constrained by a base class that is specified by the `target` parameter.
`handle-as`	Handles the property as if it were defined by the type defined by the mandatory `target` parameter.
`logger-name`	Auto-completes valid logger names and logger groups. Typically, package and class names available in the current project can be auto-completed as well as defined groups.
`spring-bean-reference`	Auto-completes the available bean names in the current project. Usually constrained by a base class that is specified by the `target` parameter.
`spring-profile-name`	Auto-completes the available Spring profile names in the project.

	Tip
	Only one provider can be active for a given property, but you can specify severalproviders if they can all manage the property in some way. Make sure to place the mostpowerful provider first, as the IDE must use the first one in the JSON section that itcan handle. If no provider for a given property is supported, no special contentassistance is provided, either.

Any

The special any provider value permits any additional values to be provided. Regularvalue validation based on the property type should be applied if this is supported.

This provider is typically used if you have a list of values and any extra valuesshould still be considered as valid.

The following example offers on and off as auto-completion values for system.state:

{"hints": [{"name": "system.state","values": [{"value": "on"},{"value": "off"}],"providers": [{"name": "any"}]}]}

Note that, in the preceding example, any other value is also allowed.

Class Reference

The class-reference provider auto-completes classes available in the project. Thisprovider supports the following parameters:

Parameter	Type	Default value	Description
`target`	`String` (`Class`)	none	The fully qualified name of the class that should be assignable to the chosen value. Typically used to filter out-non candidate classes. Note that this information can be provided by the type itself by exposing a class with the appropriate upper bound.
`concrete`	`boolean`	true	Specify whether only concrete classes are to be considered as valid candidates.

The following metadata snippet corresponds to the standard server.servlet.jsp.class-nameproperty that defines the JspServlet class name to use:

{"hints": [{"name": "server.servlet.jsp.class-name","providers": [{"name": "class-reference","parameters": {"target": "javax.servlet.http.HttpServlet"}}]}]}

Handle As

The handle-as provider lets you substitute the type of the property to a morehigh-level type. This typically happens when the property has a java.lang.String type,because you do not want your configuration classes to rely on classes that may not beon the classpath. This provider supports the following parameters:

Parameter	Type	Default value	Description
`target`	`String` (`Class`)	none	The fully qualified name of the type to consider for the property. This parameter is mandatory.

The following types can be used:

Any java.lang.Enum: Lists the possible values for the property. (We recommenddefining the property with the Enum type, as no further hint should be required forthe IDE to auto-complete the values.)
java.nio.charset.Charset: Supports auto-completion of charset/encoding values (such asUTF-8)
java.util.Locale: auto-completion of locales (such as en_US)
org.springframework.util.MimeType: Supports auto-completion of content type values(such as text/plain)
org.springframework.core.io.Resource: Supports auto-completion of Spring’s Resourceabstraction to refer to a file on the filesystem or on the classpath. (such asclasspath:/sample.properties)

	Tip
	If multiple values can be provided, use a `Collection` or Array type to teach theIDE about it.

The following metadata snippet corresponds to the standard spring.liquibase.change-logproperty that defines the path to the changelog to use. It is actually used internally as aorg.springframework.core.io.Resource but cannot be exposed as such, because we need tokeep the original String value to pass it to the Liquibase API.

{"hints": [{"name": "spring.liquibase.change-log","providers": [{"name": "handle-as","parameters": {"target": "org.springframework.core.io.Resource"}}]}]}

Logger Name

The logger-name provider auto-completes valid logger names andlogger groups. Typically,package and class names available in the current project can be auto-completed. If groupsare enabled (default) and if a custom logger group is identified in the configuration,auto-completion for it should be provided. Specific frameworks may have extra magic loggernames that can be supported as well.

This provider supports the following parameters:

Parameter	Type	Default value	Description
`group`	`boolean`	`true`	Specify whether known groups should be considered.

Since a logger name can be any arbitrary name, this provider should allow anyvalue but could highlight valid package and class names that are not available in theproject’s classpath.

The following metadata snippet corresponds to the standard logging.level property. Keysare logger names, and values correspond to the standard log levels or any customlevel. As Spring Boot defines a few logger groups out-of-the-box, dedicated value hintshave been added for those.

{"hints": [{"name": "logging.level.keys","values": [{"value": "root","description": "Root logger used to assign the default logging level."},{"value": "sql","description": "SQL logging group including Hibernate SQL logger."},{"value": "web","description": "Web logging group including codecs."}],"providers": [{"name": "logger-name"}]},{"name": "logging.level.values","values": [{"value": "trace"},{"value": "debug"},{"value": "info"},{"value": "warn"},{"value": "error"},{"value": "fatal"},{"value": "off"}],"providers": [{"name": "any"}]}]}

Spring Bean Reference

The spring-bean-reference provider auto-completes the beans that are defined inthe configuration of the current project. This provider supports the following parameters:

Parameter	Type	Default value	Description
`target`	`String` (`Class`)	none	The fully qualified name of the bean class that should be assignable to the candidate. Typically used to filter out non-candidate beans.

The following metadata snippet corresponds to the standard spring.jmx.server propertythat defines the name of the MBeanServer bean to use:

{"hints": [{"name": "spring.jmx.server","providers": [{"name": "spring-bean-reference","parameters": {"target": "javax.management.MBeanServer"}}]}]}

	Note
	The binder is not aware of the metadata. If you provide that hint, you still needto transform the bean name into an actual Bean reference using by the `ApplicationContext`.

Spring Profile Name

The spring-profile-name provider auto-completes the Spring profiles that aredefined in the configuration of the current project.

The following metadata snippet corresponds to the standard spring.profiles.activeproperty that defines the name of the Spring profile(s) to enable:

{"hints": [{"name": "spring.profiles.active","providers": [{"name": "spring-profile-name"}]}]}

B.3Generating Your Own Metadata by Using the Annotation Processor

You can easily generate your own configuration metadata 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 iscompiled. To use the processor, include a dependency onspring-boot-configuration-processor.

With Maven the dependency should be declared as optional, as shown in the followingexample:

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

With Gradle 4.5 and earlier, the dependency should be declared in the compileOnlyconfiguration, as shown in the following example:

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

With Gradle 4.6 and later, the dependency should be declared in the annotationProcessorconfiguration, as shown in the following example:

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

If you are using an additional-spring-configuration-metadata.json file, thecompileJava task should be configured to depend on the processResources task, as shownin the following example:

compileJava.dependsOn(processResources)

This dependency ensures that the additional metadata is available when the annotationprocessor runs during compilation.

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

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

Properties are discovered through the presence of standard getters and setters withspecial handling for collection types (that is detected even if only a getter is present).The annotation processor also supports the use of the @Data, @Getter, and @Setterlombok annotations.

Note

If you are using AspectJ in your project, you need to make sure that the annotationprocessor runs only once. There are several ways to do this. With Maven, you canconfigure the maven-apt-plugin explicitly and add the dependency to the annotationprocessor only there. You could also let the AspectJ plugin run all the processingand disable annotation processing in the maven-compiler-plugin configuration, asfollows:

<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><configuration><proc>none</proc></configuration></plugin>

B.3.1Nested Properties

The annotation processor automatically considers inner classes as nested properties.Consider the following class:

@ConfigurationProperties(prefix="server")public class ServerProperties {private String name;private Host host;// ... getter and setterspublic static class Host {private String ip;private int port;// ... getter and setters}}

The preceding example produces metadata information for server.name, server.host.ip,and server.host.port properties. You can use the @NestedConfigurationPropertyannotation on a field to indicate that a regular (non-inner) class should be treated asif it were nested.

	Tip
	This has no effect on collections and maps, as those types are automaticallyidentified, and a single metadata property is generated for each of them.

B.3.2Adding Additional Metadata

Spring Boot’s configuration file handling is quite flexible, and it is often the casethat properties may exist that are not bound to a @ConfigurationProperties bean. Youmay also need to tune some attributes of an existing key. To support such cases and letyou provide custom "hints", the annotation processor automatically merges itemsfrom META-INF/additional-spring-configuration-metadata.json into the main metadatafile.

If you refer to a property that has been detected automatically, the description,default value, and deprecation information are overridden, if specified. If the manualproperty declaration is not identified in the current module, it is added as a newproperty.

The format of the additional-spring-configuration-metadata.json file is exactly the sameas the regular spring-configuration-metadata.json. The additional properties file isoptional. If you do not have any additional properties, do not add the file.