You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@grails.apache.org by ja...@apache.org on 2026/07/23 20:06:46 UTC

(grails-core) 09/10: Document automated configuration metadata

This is an automated email from the ASF dual-hosted git repository.

jamesfredley pushed a commit to branch feature/automated-configuration-metadata
in repository https://gitbox.apache.org/repos/asf/grails-core.git

commit 41433386f12bea32287d966a0f4b3f68179862a0
Author: James Fredley <ja...@users.noreply.github.com>
AuthorDate: Thu Jul 23 14:20:04 2026 -0400

    Document automated configuration metadata
    
    Assisted-by: opencode:gpt-5.6-sol
---
 grails-doc/src/en/guide/conf/config.adoc | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/grails-doc/src/en/guide/conf/config.adoc b/grails-doc/src/en/guide/conf/config.adoc
index 7a20585f1d..d5da23da10 100644
--- a/grails-doc/src/en/guide/conf/config.adoc
+++ b/grails-doc/src/en/guide/conf/config.adoc
@@ -112,6 +112,28 @@ class MyService {
 }
 ----
 
+=== Configuration Metadata
+
+Grails framework modules publish standard Spring Boot configuration metadata in
+`META-INF/spring-configuration-metadata.json`. IDEs use this metadata for key completion, types, descriptions, defaults,
+and value hints. The Grails configuration report command and the
+link:../ref/Configuration/Application%20Properties.html[Application Properties reference] use its property and group
+entries.
+
+For configuration classes written in Groovy, Grails collects metadata with a compiler AST transformation. The
+transformation stores metadata independently in each compiled `@ConfigurationProperties` class, and the build merges
+those class payloads after compilation. Java configuration classes are inspected from their compiled bytecode. This
+avoids Java annotation processing on Groovy sources, which would interfere with incremental Groovy compilation.
+
+The generated metadata describes bindable fields and bean properties. A module can also provide
+`META-INF/additional-spring-configuration-metadata.json` for descriptions, hints, legacy or indirect properties, and
+other details that cannot be derived safely from bytecode. Curated values override generated values for the same
+property.
+
+Only compile-time constant Groovy initializers are emitted as generated defaults. Defaults calculated by constructors,
+method calls, environment checks, system properties, or other dynamic expressions are intentionally omitted unless a
+curated metadata overlay supplies an authoritative value.
+
 === GrailsConfigurationAware Interface
 
 Accessing configuration dynamically at runtime can have a small effect on application performance. An alternative approach is to implement the link:{api}grails/core/support/GrailsConfigurationAware.html[GrailsConfigurationAware] interface, which provides a `setConfiguration` method that accepts the application configuration as a parameter when the class is initialized. You can then assign relevant configuration properties to instance properties on the class for later usage.