Replace config-properties.yml with standard spring-configuration-metadata.json

[jamesfredley]

Summary

Replaces the custom config-properties.yml metadata with Spring Boot's standard spring-configuration-metadata.json format, distributed across the 9 modules that own each set of properties. This gives IDEs (IntelliJ, VS Code, Eclipse STS) auto-completion and hover documentation for Grails configuration properties out of the box.

The generated Application Properties.adoc reference recovers all content from the previous hand-written doc (descriptions, defaults, sections) while making it maintainable - each module owns its own metadata JSON and the doc is generated at build time. Compared to the old 135-property hand-written doc, the generated doc now covers 206 properties across 24 sections.

For Grails 8, a follow-up initiative (#15469) proposes migrating to @ConfigurationProperties annotated classes with the Spring Boot annotation processor, which would auto-generate the metadata JSON at compile time and eliminate manual maintenance entirely.

What Changed

New spring-configuration-metadata.json Files (9 modules)

Module	Properties	Categories
grails-core	45	Core, Events, JSON & Converters, Internationalization, GORM, DataSource
grails-web-core	33	Web & Controllers, CORS, MIME Types, Static Resources, URL Mappings, Scaffolding
grails-gsp	13	Views & GSP
grails-databinding	5	Data Binding
grails-data-hibernate5/core	3	Hibernate
grails-cache	6	Cache Plugin
grails-data-hibernate5/dbmigration	15	Database Migration Plugin
grails-data-mongodb/grails-plugin	23	MongoDB GORM Plugin (connections, pools, SSL)
grails-views-gson	9	JSON Views

Total: 152 properties across 9 modules, generating a 866-line reference doc with 24 sections.

Refactored ConfigReportCommand

• Reads META-INF/spring-configuration-metadata.json from the classpath via ClassLoader.getResources() instead of custom YAML
• Uses ConfigPropertyMetadata and MetadataResult immutable data classes instead of raw maps
• Separates environment-derived properties (from System.getenv()) into their own report section
• Groups unknown runtime properties into an "Other Properties" section
• Removed SnakeYAML dependency for metadata parsing

Generated Documentation

• generateConfigReference Gradle task in grails-doc/build.gradle reads metadata JSON from all 9 module JARs and generates Application Properties.adoc during publishGuide
• Generated doc includes 24 sections with descriptions and defaults preserved from the original hand-written doc
• Environment-specific configuration section at the top with YAML and Groovy examples, including list of default environments (development, test, production)
• "Plugin References" section at the bottom linking directly to config property anchors in external plugin docs

Removed

• grails-core/src/main/resources/META-INF/grails/config-properties.yml (814 lines of custom format)
• grails-doc/src/en/ref/Configuration/Application Properties.adoc (1440 lines of checked-in content, now generated)

Companion PRs for External Plugins

Properties for plugins with their own repositories now have spring-configuration-metadata.json in their respective repos, each with a generated properties reference doc:

• Spring Security (145 properties, 14 groups) - docs: add configuration metadata reference grails-spring-security#1210
• Asset Pipeline (23 properties, 1 group) - Add asset pipeline configuration metadata wondrify/asset-pipeline#445

The "Plugin References" section in the generated doc links directly to the configuration properties section in each plugin's published documentation:

• Spring Security: https://apache.github.io/grails-spring-security/snapshot/core-plugin/guide/index.html#_configuration_properties
• Asset Pipeline: https://wondrify.github.io/asset-pipeline/

Future Direction

For Grails 8, issue #15469 tracks migrating to @ConfigurationProperties annotated classes with the spring-boot-configuration-processor. Five modules already have @ConfigurationProperties classes (DataBindingConfigurationProperties, GrailsCorsConfiguration, CachePluginConfiguration, JsonViewConfiguration, MarkupViewConfiguration) and could adopt auto-generation immediately. Modules using Groovy DSL config (like Spring Security's DefaultSecurityConfig.groovy) would need a phased migration.

Testing

• All 17 ConfigReportCommandSpec tests pass
• generateConfigReference Gradle task verified locally (866-line doc, 24 sections)
• All 9 JSON files validated
• CodeNarc clean
• Compared against old hand-written doc: zero real properties lost (13 external plugin properties are now linked, 71 new properties added)

[jamesfredley]

Screenshot: The-Grails-Framework-7-0-8-SNAPSHOT-02-20-2026_07_40_PM.pdf

[Copilot]

Pull request overview

Adds a hybrid ConfigReportCommand to Grails that merges curated configuration-property metadata (from a new classpath YAML file) with runtime-resolved values from Spring’s ConfigurableEnvironment, and includes a new grails-test-examples/config-report sample app to validate the output format end-to-end.

Changes:

• Introduces ConfigReportCommand to generate a categorized AsciiDoc report using static metadata + runtime overrides, with an “Other Properties” section for non-metadata keys.
• Adds META-INF/grails/config-properties.yml containing categorized property metadata (descriptions + defaults).
• Adds/updates unit + integration tests, including a new grails-test-examples/config-report module wired into settings.gradle.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
settings.gradle	Adds the new grails-test-examples-config-report included build project.
grails-core/src/main/groovy/grails/dev/commands/ConfigReportCommand.groovy	Implements the hybrid config report generator (runtime collection + metadata merge + AsciiDoc output).
grails-core/src/main/resources/META-INF/grails/config-properties.yml	Supplies categorized metadata used to render known properties.
grails-core/src/test/groovy/grails/dev/commands/ConfigReportCommandSpec.groovy	Unit tests for property collection, metadata loading, escaping, and report layout.
grails-test-examples/config-report/**	New sample application + integration spec validating runtime config capture and report structure.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jamesfredley]

@jdaugherty As long as CI passes, I think this is ready to review as the hybrid approach to generate the Configuration Reference.

[jamesfredley]

Updated screenshot with environments section: The-Grails-Framework-7-0-8-SNAPSHOT-02-26-2026_10_37_AM.pdf

[jamesfredley]

Follow-up: Configuration Metadata for Other Plugins

This PR standardizes grails-core on spring-configuration-metadata.json. The following companion PRs add the same standard to ecosystem plugins:

• Grails Spring Security Core: docs: add configuration metadata reference grails-spring-security#1210
• Asset Pipeline: Add asset pipeline configuration metadata wondrify/asset-pipeline#445

Each plugin can follow the same pattern: add a META-INF/spring-configuration-metadata.json with groups/properties, then add a Gradle task to generate an AsciiDoc properties reference table for their docs. The generateConfigReference task in grails-doc/build.gradle will automatically pick up any new JSON files from plugin JARs on the classpath.