This version is still in development and is not considered stable yet. For the latest stable version, please use Spring Boot 3.3.2! |
Metadata Format
Configuration metadata files are located inside jars under META-INF/spring-configuration-metadata.json
.
They use a JSON format with items categorized under either “groups” or “properties” and additional values hints categorized 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 in your application.properties
/application.yaml
, as follows:
-
Properties
-
YAML
server.port=9090
server.address=127.0.0.1
server:
port: 9090
address: 127.0.0.1
The “groups” are higher level items that do not themselves specify a value but instead provide a contextual grouping for properties.
For example, the server.port
and server.address
properties are part of the server
group.
It is not required that every “property” has a “group”. Some properties might exist in their own right. |
Finally, “hints” are additional information used to assist the user in configuring a given property.
For example, when a developer is configuring the spring.jpa.hibernate.ddl-auto
property, a tool can use the hints to offer some auto-completion help for the none
, validate
, update
, create
, and create-drop
values.
Group Attributes
The JSON object contained in the groups
array can contain the attributes shown in the following table:
Name | Type | Purpose |
---|---|---|
|
String |
The full name of the group. This attribute is mandatory. |
|
String |
The class name of the data type of the group.
For example, if the group were based on a class annotated with |
|
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 ( |
|
String |
The class name of the source that contributed this group.
For example, if the group were based on a |
|
String |
The full name of the method (include parenthesis and argument types) that contributed this group (for example, the name of a |
Property Attributes
The JSON object contained in the properties
array can contain the attributes described in the following table:
Name | Type | Purpose |
---|---|---|
|
String |
The full name of the property.
Names are in lower-case period-separated form (for example, |
|
String |
The full signature of the data type of the property (for example, |
|
String |
A short description of the property 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 ( |
|
String |
The class name of the source that contributed this property.
For example, if the property were from a class annotated with |
|
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 |
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 |
The JSON object contained in the deprecation
attribute of each properties
element can contain the following attributes:
Name | Type | Purpose |
---|---|---|
|
String |
The level of deprecation, which can be either |
|
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 ( |
|
String |
The full name of the property that replaces this deprecated property. If there is no replacement for this property, it may be omitted. |
|
String |
The version in which the property became deprecated. Can be omitted. |
Prior to Spring Boot 1.3, a single deprecated boolean attribute can be used instead of the deprecation element.
This is still supported in a deprecated fashion and should 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 deprecated property.
For instance, assume that the my.app.target
property was confusing and was renamed to my.app.name
.
The following example shows how to handle that situation:
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.DeprecatedConfigurationProperty;
@ConfigurationProperties("my.app")
public class MyProperties {
private String name;
public String getName() {
return this.name;
}
public void setName(String name) {
this.name = name;
}
@Deprecated
@DeprecatedConfigurationProperty(replacement = "my.app.name")
public String getTarget() {
return this.name;
}
@Deprecated
public void setTarget(String target) {
this.name = target;
}
}
There is no way to set a level .
warning is always assumed, since code is still handling the property.
|
The preceding code makes sure that the deprecated property still works (delegating to the name
property behind the scenes).
Once the getTarget
and setTarget
methods can be removed from your public API, the automatic deprecation hint in the metadata goes away as well.
If you want to keep a hint, adding manual metadata with an error
deprecation level ensures that users are still informed about that property.
Doing so is particularly useful when a replacement
is provided.
Hint Attributes
The JSON object contained in the hints
array can contain the attributes shown in the following table:
Name | Type | Purpose |
---|---|---|
|
String |
The full name of the property to which this hint refers.
Names are in lower-case period-separated form (such as |
|
ValueHint[] |
A list of valid values as defined by the |
|
ValueProvider[] |
A list of providers as defined by the |
The JSON object contained in the values
attribute of each hint
element can contain the attributes described in the following table:
Name | Type | Purpose |
---|---|---|
|
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. |
|
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 ( |
The JSON object contained in the providers
attribute of each hint
element can contain the attributes described in the following table:
Name | Type | Purpose |
---|---|---|
|
String |
The name of the provider to use to offer additional content assistance for the element to which the hint refers. |
|
JSON object |
Any additional parameter that the provider supports (check the documentation of the provider for more details). |
Repeated Metadata Items
Objects with the same “property” and “group” name can appear multiple times within a metadata file. For example, you could bind two separate classes to the same prefix, with each having potentially overlapping property names. While the same names appearing in the metadata multiple times should not be common, consumers of metadata should take care to ensure that they support it.