Skip to content

Add symbol processor for configuration metadata - #51375

Open
salatmaster wants to merge 3 commits into
spring-projects:mainfrom
salatmaster:gh-28046-ksp-configuration-processor
Open

Add symbol processor for configuration metadata#51375
salatmaster wants to merge 3 commits into
spring-projects:mainfrom
salatmaster:gh-28046-ksp-configuration-processor

Conversation

@salatmaster

Copy link
Copy Markdown

This adds spring-boot-configuration-symbol-processor, a KSP processor that generates configuration metadata for Kotlin sources, as an alternative to running the annotation processor through kapt. It reuses the metadata model of the existing annotation processor, so the generated META-INF/spring-configuration-metadata.json is identical in format.

Besides removing the need for kapt, it fixes metadata that kapt currently loses. For a data class with Kotlin defaults:

@ConfigurationProperties("demo")
data class DemoProperties(val port: Int = 8080, val name: String = "demo")

kapt generates a stub with two constructors, the annotation processor can no longer deduce the bind constructor, and no properties end up in the metadata at all — only the group. The symbol processor describes both properties. KDoc on constructor parameters (@property) is picked up as well, which kapt drops.

Supported: constructor and JavaBean binding, @DefaultValue, @Name, nested groups, @NestedConfigurationProperty, @ConfigurationProperties on a method, actuator endpoints, deprecations, KDoc descriptions, merging of additional-spring-configuration-metadata.json, and @ConfigurationPropertiesSource.

Known limitations, all covered in the new appendix section:

  • Default values declared with an initializer are invisible to KSP ([feature request] Retrieve property default value for compile time constants google/ksp#1868). kapt does not expose them either, so this is not a regression, and @DefaultValue still works.
  • Additional metadata has to be located with a processor option, since KSP gives a processor no access to module resources.
  • A module has to apply either this processor or the annotation processor, as both write the same file.
  • Endpoint annotations are matched directly rather than through meta-annotations.

Tests drive the processor through the KSP2 API directly, so there is no third-party test dependency. The processor is compiled against symbol-processing-api 2.3.0 and declares it as compileOnly, so the KSP version stays under the user's control.

I'm aware this is marked as pending design work, so please treat it as a concrete proposal rather than a finished feature — happy to rework it if you'd rather see a different shape, such as an abstraction shared with the annotation processor.

See gh-28046

@spring-projects-issues spring-projects-issues added the status: waiting-for-triage An issue we've not yet triaged label Aug 12, 2026
@salatmaster
salatmaster force-pushed the gh-28046-ksp-configuration-processor branch from ae9a47e to 60d3b03 Compare August 12, 2026 14:07
Add spring-boot-configuration-symbol-processor, a Kotlin Symbol
Processing (KSP) processor that writes the configuration metadata of
Kotlin types. It reuses the metadata model of the annotation processor,
so the generated META-INF/spring-configuration-metadata.json is
identical in format, and it lets a Kotlin project generate its metadata
without kapt.

The processor supports constructor binding and JavaBean binding, nested
groups, @ConfigurationProperties on a method, actuator endpoints,
descriptions taken from KDoc, deprecations, and the merging of
META-INF/additional-spring-configuration-metadata.json. A type annotated
with @ConfigurationPropertiesSource is described in a file of its own.

Kotlin types are reported using their JVM names, so that a List<String>
property is described as java.util.List<java.lang.String> as it is when
the annotation processor runs.

See spring-projectsgh-28046

Signed-off-by: Areg Iazychian <abstractcoderx@gmail.com>
Add the symbol processor to spring-boot-dependencies so that a project
can declare it without having to specify its version.

See spring-projectsgh-28046

Signed-off-by: Areg Iazychian <abstractcoderx@gmail.com>
Describe how to apply the symbol processor, the types that it supports,
how to contribute additional metadata, and its limitations. Note that a
module has to apply either the annotation processor or the symbol
processor, as both write the same metadata file.

See spring-projectsgh-28046

Signed-off-by: Areg Iazychian <abstractcoderx@gmail.com>
@salatmaster
salatmaster force-pushed the gh-28046-ksp-configuration-processor branch from 60d3b03 to 86bbb93 Compare August 12, 2026 14:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

status: waiting-for-triage An issue we've not yet triaged

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants