Modernize MIME negotiation and serialization for Spring Boot 4.1

[codeconsole]

Summary

• bridge Grails MIME types to Spring MediaType and integrate negotiation with Spring MVC
• remove static MIME negotiation state and resolve strategy bean ambiguity
• use Spring MVC message converters and the Boot JsonMapper for ordinary JSON responses, with legacy compatibility fallbacks
• replace named legacy JSON configuration with an injectable, request-safe Jackson registry shared by render, respond, and direct serialization
• extract XML HTTP payload support into the optional grails-xml module without changing XML plugin descriptors
• select XML converters from Spring MVC, keep new REST artefacts JSON-only by default, and preserve secure legacy XML compatibility
• render REST validation errors as RFC 9457 application/problem+json; keep Vnd.Error opt-in and deprecate legacy XML error formats
• add an optional grails-spring-hateoas adapter module, deprecate HAL XML, and keep Atom/feed rendering opt-in
• statically compile changed production Groovy paths; Java additions use the Java 21 baseline

Lines of code

Area	Added	Removed	Net	Deprecated	Net after deprecated removal
Production	1,790	220	+1,570	574	+996
Tests	1,715	194	+1,521	0	+1,521
Documentation	612	37	+575	0	+575
Total	4,117	451	+3,666	574	+3,092

Added and removed counts come from git diff --numstat upstream/8.0.x...HEAD; pure renames count as zero. Test sources are counted as tests. grails-doc and Markdown files are counted as documentation. Build/module wiring is counted as production.

Tests and documentation account for +2,096 LOC. Production is +1,570 net before future deprecated-code removal and +996 afterward. The remaining production growth implements Spring MVC negotiation/converter bridges, named Jackson configurations, Jackson domain compatibility, Problem Details, the optional XML boundary, and the optional Spring HATEOAS adapter.

The deprecated count is current source covered by @Deprecated(since = "8.0", forRemoval = false): the legacy JSON configuration/marshaller API blocks plus Vnd.Error XML, legacy XML validation marshalling, and HAL XML renderer classes. These remain supported on 8.0.x for a deprecation cycle.

Compatibility and migration

• Plugin descriptors remain XML and are unaffected; grails-xml controls application HTTP XML payload support only.
• NamedJsonConfigurationRegistry replaces JSON.createNamedConfig(...) and JSON.use(...) for named registration and direct serialization.
• render value, jsonConfiguration: 'deep' and respond value, jsonConfiguration: 'deep' select the same registered Jackson configuration.
• Legacy named JSON configurations remain supported as a fallback while their APIs are deprecated.
• Per-response include/exclude projections retain the legacy converter path.
• Applications can explicitly register Vnd.Error JSON, XML compatibility renderers, HAL renderers, and Atom renderers.
• New REST artefacts advertise JSON only. XML endpoints add grails-xml and opt the artefact into XML.

Verification

Scoped affected-module tests, checks, dependency validation, profile builds, and guide builds passed with --max-workers=2. The final named-Jackson change ran all tests and checks for grails-web-common, grails-converters, grails-controllers, and grails-rest-transforms, plus the Grails guide build.

A full repository sweep was intentionally not run on the development machine because of its resource constraints; broader validation is left to CI.

[codecov]

Codecov Report

❌ Patch coverage is 82.56000% with 109 lines in your changes missing coverage. Please review.
✅ Project coverage is 55.1599%. Comparing base (d71c218) to head (1fb9890).
⚠️ Report is 95 commits behind head on 8.0.x.

Files with missing lines	Patch %	Lines
...converters/jackson/GrailsDomainJsonSerializer.java	78.2609%	4 Missing and 11 partials ⚠️
...ns/web/rest/render/json/DefaultJsonRenderer.groovy	69.7674%	2 Missing and 11 partials ⚠️
...s/web/mime/GrailsContentNegotiationStrategy.groovy	71.7949%	3 Missing and 8 partials ⚠️
...gins/web/rest/render/xml/DefaultXmlRenderer.groovy	66.6667%	1 Missing and 7 partials ⚠️
...lugins/testing/GrailsMockHttpServletRequest.groovy	50.0000%	5 Missing and 1 partial ⚠️
...uration/XmlConvertersConfigurationInitializer.java	90.9091%	4 Missing and 2 partials ⚠️
...onverters/json/NamedJsonConfigurationRegistry.java	83.8710%	2 Missing and 3 partials ⚠️
...converters/jackson/GrailsJsonMapperCustomizer.java	81.4815%	3 Missing and 2 partials ⚠️
...in/groovy/org/grails/io/support/SpringIOUtils.java	0.0000%	5 Missing ⚠️
...grails/converters/json/NamedJsonConfiguration.java	82.6087%	2 Missing and 2 partials ⚠️
... and 11 more

Additional details and impacted files

@@                Coverage Diff                 @@
##                8.0.x     #16237        +/-   ##
==================================================
+ Coverage     54.7020%   55.1599%   +0.4579%     
- Complexity      20424      20729       +305     
==================================================
  Files            2101       2119        +18     
  Lines          100978     101474       +496     
  Branches        17907      17988        +81     
==================================================
+ Hits            55237      55973       +736     
+ Misses          37877      37530       -347     
- Partials         7864       7971       +107     

Files with missing lines	Coverage Δ
...erters/src/main/groovy/grails/converters/JSON.java	32.8520% <ø> (+8.3033%)	⬆️
...s/plugins/converters/ConvertersGrailsPlugin.groovy	100.0000% <100.0000%> (ø)
...g/grails/web/converters/ConvertersExtension.groovy	66.6667% <ø> (+9.5238%)	⬆️
...figuration/ConvertersConfigurationInitializer.java	82.9546% <ø> (-4.3470%)	⬇️
...converters/jackson/SpringErrorsJsonSerializer.java	100.0000% <100.0000%> (ø)
...plugins/databinding/DataBindingGrailsPlugin.groovy	100.0000% <ø> (ø)
...ils/plugins/web/mime/MimeTypesConfiguration.groovy	82.9268% <100.0000%> (+0.8755%)	⬆️
.../render/errors/ValidationProblemDetailFactory.java	100.0000% <100.0000%> (ø)
...s/web/rest/plugin/RestResponderGrailsPlugin.groovy	71.4286% <100.0000%> (+6.7227%)	⬆️
...ins/web/rest/render/DefaultRendererRegistry.groovy	72.8814% <100.0000%> (+2.1917%)	⬆️
... and 51 more

... and 26 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[codeconsole]

Deprecation migration examples

This comment maps every API deprecated by this PR to its modern replacement. Overloads are grouped where their migration is identical.

The XML migrations intentionally change the response representation to JSON. The deprecated XML implementations remain available in grails-xml for clients that cannot migrate immediately.

1. JSON.registerObjectMarshaller(...) (all four overloads)

This covers (Class, Closure), (Class, int, Closure), (ObjectMarshaller), and (ObjectMarshaller, int).

Before:

JSON.registerObjectMarshaller(Book, 100) { Book book ->
    [id: book.id, title: book.title]
}

After, for an application-wide Jackson representation:

import org.springframework.boot.jackson.autoconfigure.JsonMapperBuilderCustomizer
import org.springframework.context.annotation.Bean
import tools.jackson.databind.module.SimpleModule

@Bean
JsonMapperBuilderCustomizer bookJsonCustomizer() {
    { builder ->
        builder.addModule(new SimpleModule()
                .addSerializer(Book, new BookValueSerializer()))
    } as JsonMapperBuilderCustomizer
}

BookValueSerializer is a Jackson 3 ValueSerializer<Book>. Jackson module registration replaces legacy marshaller priority; serializer/module ordering should be made explicit when serializers overlap.

2. JSON.withDefaultConfiguration(...)

Before:

JSON.withDefaultConfiguration {
    it.registerObjectMarshaller(Book) { Book book ->
        [id: book.id, title: book.title]
    }
}

After:

@Bean
JsonMapperBuilderCustomizer bookJsonCustomizer() {
    { builder ->
        builder.addModule(new SimpleModule()
                .addSerializer(Book, new BookValueSerializer()))
    } as JsonMapperBuilderCustomizer
}

This customizes Spring Boot's managed JsonMapper, so the representation is shared by respond, Spring MVC message conversion, and other Jackson integrations.

3. JSON.createNamedConfig(...)

Before:

JSON.createNamedConfig('deep') {
    it.registerObjectMarshaller(Type, deepObjectMarshaller)
    it.registerObjectMarshaller(Category, deepObjectMarshaller)
}

After:

import grails.converters.json.NamedJsonConfigurationRegistry

class BootStrap {
    NamedJsonConfigurationRegistry namedJsonConfigurationRegistry

    def init = { servletContext ->
        namedJsonConfigurationRegistry.register('deep') {
            it.serializer(Type, new TypeValueSerializer())
            it.serializer(Category, new CategoryValueSerializer())
        }
    }
}

The named configuration derives an isolated mapper from Boot's configured JsonMapper; it does not mutate global or thread-local converter state.

4. JSON.use(String, Closure)

Before:

String json = JSON.use('deep') {
    new JSON(book).toString()
}

After, for direct serialization:

String json = namedJsonConfigurationRegistry.writeValueAsString('deep', book)

Or stream directly:

namedJsonConfigurationRegistry.writeValue('deep', writer, book)

For controller responses, the same configuration works with both APIs:

render book, jsonConfiguration: 'deep'
respond book, jsonConfiguration: 'deep'

5. JSON.use(String)

Before:

JSON.use('deep')
try {
    String json = new JSON(book).toString()
} finally {
    JSON.use('default')
}

After:

String json = namedJsonConfigurationRegistry.writeValueAsString('deep', book)

Configuration is selected explicitly per operation, eliminating mutable thread-local state.

6. JSON.getNamedConfig(String)

Before:

def configuration = JSON.getNamedConfig('deep')

After:

ObjectWriter writer = namedJsonConfigurationRegistry.writer('deep')
String json = writer.writeValueAsString(book)

Registration remains encapsulated in NamedJsonConfigurationRegistry.register(...); consumers receive the configured, immutable-style Jackson writer used for serialization.

7. HalXmlRenderer

Before:

import grails.rest.render.hal.HalXmlRenderer

beans = {
    halBookRenderer(HalXmlRenderer, Book)
}

After, using Grails HAL JSON:

import grails.rest.render.hal.HalJsonRenderer

beans = {
    halBookRenderer(HalJsonRenderer, Book)
}

Clients negotiate it with:

Accept: application/hal+json

Applications that prefer Spring's hypermedia model can instead add the optional grails-spring-hateoas module.

8. HalXmlCollectionRenderer

Before:

import grails.rest.render.hal.HalXmlCollectionRenderer

beans = {
    halBooksRenderer(HalXmlCollectionRenderer, Book)
}

After:

import grails.rest.render.hal.HalJsonCollectionRenderer

beans = {
    halBooksRenderer(HalJsonCollectionRenderer, Book)
}

Clients use Accept: application/hal+json rather than application/hal+xml.

9. VndErrorXmlRenderer

Before:

import grails.rest.render.errors.VndErrorXmlRenderer

beans = {
    vndXmlErrorRenderer(VndErrorXmlRenderer)
}

// Client: Accept: application/vnd.error+xml
respond book.errors

After, using the default RFC 9457 validation response:

// No Vnd.Error renderer registration is required.
// Client: Accept: application/json or application/problem+json
respond book.errors

The response uses application/problem+json and status 422 for validation failures.

10. XML ValidationErrorsMarshaller

Before:

import grails.converters.XML
import org.grails.web.converters.marshaller.xml.ValidationErrorsMarshaller

XML.registerObjectMarshaller(new ValidationErrorsMarshaller(), 100)
render book.errors as XML

After:

// Client: Accept: application/json or application/problem+json
respond book.errors

Grails renders the validation errors as RFC 9457 application/problem+json. Keep the deprecated marshaller only while an existing client still requires the legacy XML error schema.

[codeconsole]

Why grails-xml is a separate module

grails-xml was separated so XML support is an optional application capability rather than a mandatory part of Grails' core REST stack.

The reasons are:

• Most new REST APIs use JSON. JSON-only applications should not carry XML converters, renderers, data binding, marshallers, and XML-specific dependencies.
• Spring Boot 4.1 organizes serialization around media-type-specific HTTP message converters. An optional XML module fits that model: JSON follows the normal Boot/Jackson path, while XML infrastructure is installed only when requested.
• The module creates a clear boundary around XML HTTP payload behavior:
  • XML rendering and conversion
  • XML request data binding
  • legacy XML marshalling
  • HAL XML compatibility
  • Vnd.Error XML compatibility
• Legacy XML support can remain available during migration without keeping deprecated XML formats permanently coupled to the core REST module.
• Future removal or replacement of legacy XML components becomes safer because those components no longer intersect the core JSON path.

Applications that need XML add the module:

dependencies {
    implementation 'org.apache.grails:grails-xml'
}

They can then advertise XML on the relevant REST artefact:

static responseFormats = ['json', 'xml']

JSON-only applications do not need to do anything.

Conceptually, the boundary is:

Core REST support
├── JSON / Problem Details / content negotiation
└── optional grails-xml
    ├── XML HTTP conversion
    ├── XML data binding
    ├── legacy XML marshalling
    ├── HAL XML compatibility
    └── Vnd.Error XML compatibility

This separation concerns application HTTP request and response payloads. It does not remove or change XML plugin descriptors; plugin descriptor publication and consumption are a separate concern and remain supported.

The intent is a smaller, modular modern default—not to declare XML unsupported.

[testlens-app]

✅ All tests passed ✅

🏷️ Commit: 1fb9890
▶️ Tests: 29000 executed
⚪️ Checks: 91/91 completed

---

Learn more about TestLens at testlens.app/docs.

[jdaugherty]

This is an extremely large change that I think needs deferred to 8.1 or possibly 9 with feedback from multiple committers to merge.

[codeconsole]

@jdaugherty I think it is too much for 8.1. I am fine with 9 if we can get it reviewed in a timely manner and released as a 9.0 milestone prior to any 8.1 milestone