Skip to content

9.0 (fix): Spring format negotiation follow-ups: problem+xml ordering, fallback wording - #17102

Open
codeconsole wants to merge 5 commits into
apache:9.0.xfrom
codeconsole:docs/spring-format-negotiation-fallback-wording-9.0.x
Open

codeconsole wants to merge 5 commits into
apache:9.0.xfrom
codeconsole:docs/spring-format-negotiation-fallback-wording-9.0.x

Conversation

@codeconsole

@codeconsole codeconsole commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Follow-ups to #16996 (grails.mime.negotiation.spring).

An unconfigured application/problem+xml is the XML type a +xml type comes ahead of

The Grails rules read application/problem+xml, where no type of grails.mime.types names it, as application/xml, so a later +xml type of equal quality comes ahead of it: Accept: application/problem+xml, application/atom+xml is the atom format. With the setting, the +xml preference looked only for application/xml and text/xml, so the same header was xml. It now takes an unconfigured application/problem+xml as the XML type too, for the Grails formats and for what Spring MVC writes for a request a URL mapping handles.

What counts as configured is what DefaultAcceptHeaderParser checks: a type of grails.mime.types with that name, ignoring case. Where grails.mime.types names application/problem+xml, the header is the problem format and keeps its order. A problem mapping in spring.mvc.contentnegotiation.media-types alone leaves it atom, with application/atom+xml ahead of application/problem+xml for Spring MVC, because Grails still reads the type as XML. Keeping the header's order there would have Spring MVC write problem+xml while response.format and withFormat answer atom.

SpringFormatNegotiationSpec covers the header at equal and at lower quality, with problem+xml configured in grails.mime.types, and with it mapped in Spring MVC only. FormatNegotiationComparisonSpec sends it under every configuration it compares: the Grails formats now agree, and only what Spring MVC writes differs, as it already does for application/xml, application/atom+xml. Found while flipping the default for Grails 10, where WithFormatSpec's Grails 8 feature for this header failed.

The format fallback takes every format Spring MVC's manager maps

From @matrei's approving review of #16996 (optional point 1) and the review of this pull request. A format that grails.mime.types does not list is written in the type Spring MVC's content negotiation manager maps it to. The guide, the upgrade notes, the upgrade skill and the Javadoc said that fallback takes a format spring.mvc.contentnegotiation.media-types maps. It takes any format the manager maps:

  • the data formats Grails registers with it as format aliases: those among json, xml, hal, atom, rss, csv and text that grails.mime.types lists;
  • the formats spring.mvc.contentnegotiation.media-types adds;
  • those Spring MVC registers for the types its message converters support, such as json.

The lookup ignores case, which grails.mime.types does not. So ?format=JSON and ?format=HAL are written as application/json and application/hal+json for what Spring MVC writes, while Grails resolves no format for them and respond answers 406.

The wording is corrected in contentNegotiation.adoc, upgrading90x.adoc, the grails-upgrade skill, and the Javadoc of GrailsContentNegotiationStrategy.springMediaTypesOf and GrailsFormatContentNegotiationStrategy. Spring MVC's defaults are named by example rather than listed, since they depend on the converters. The upgrade note limits the point to a format only the manager maps, and links the format resolution section through a new upgradingGrailsFormatResolution anchor. SpringFormatNegotiationSpec pins the cases:

  • with grails.mime.types lacking json, ?format=json and ?format=JSON resolve to application/json;
  • with the default grails.mime.types, ?format=HAL, ?format=CSV and ?format=Text resolve to application/hal+json, text/csv and text/plain, with no Grails format.

:grails-mimetypes:test, its codeStyle and :grails-doc:publishGuide pass.

Merge order

#17106, which makes the setting the default on 10.0.x, needs the problem+xml fix: merge this pull request, then merge 9.0.x up through 9.1.x into 10.0.x, and #17106 can then be marked ready for review.

With grails.mime.negotiation.spring, a format grails.mime.types does not
list is written in the type Spring MVC's content negotiation manager maps
it to. The guide, the upgrade notes, the upgrade skill and the Javadoc
said only spring.mvc.contentnegotiation.media-types fed that fallback, but
the manager also holds the defaults Spring MVC registers for its message
converters (json, and xml, atom, rss, smile, cbor and yaml where their
libraries are present), and it matches a format whatever its case. Say
so, and pin the json default, also as JSON, in SpringFormatNegotiationSpec.
@codecov

codecov Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 60.00000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 65.6514%. Comparing base (733397b) to head (cea86e4).

Files with missing lines Patch % Lines
...s/web/mime/GrailsContentNegotiationStrategy.groovy 50.0000% 0 Missing and 2 partials ⚠️
Additional details and impacted files

Impacted file tree graph

@@                Coverage Diff                 @@
##                9.0.x     #17102        +/-   ##
==================================================
+ Coverage     65.6431%   65.6514%   +0.0083%     
  Complexity      33022      33022                
==================================================
  Files            2446       2446                
  Lines          121408     121411         +3     
  Branches        22524      22526         +2     
==================================================
+ Hits            79696      79708        +12     
+ Misses          31647      31632        -15     
- Partials        10065      10071         +6     
Files with missing lines Coverage Δ
...railsAcceptHeaderContentNegotiationStrategy.groovy 81.8182% <100.0000%> (ø)
...mime/GrailsFormatContentNegotiationStrategy.groovy 86.6667% <ø> (ø)
...s/web/mime/GrailsContentNegotiationStrategy.groovy 75.6614% <50.0000%> (-0.6827%) ⬇️

... and 7 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.

…s do

The Grails rules read application/problem+xml, where no configured type
names it, as application/xml, and so put a later +xml type of equal
quality ahead of it: Accept: application/problem+xml,
application/atom+xml is the atom format. With grails.mime.negotiation.spring
the +xml preference looked only for application/xml and text/xml, so the
same header was the xml format.

preferringSuffixedXml becomes a method of the strategy, which knows the
configured types, and also takes an unconfigured problem+xml as the XML
type. SpringFormatNegotiationSpec gains the header at equal and lower
quality, and FormatNegotiationComparisonSpec sends it under every
configuration: only what Spring MVC writes for it differs, as it does for
application/xml, application/atom+xml.
@codeconsole codeconsole changed the title 9.0 (docs): Describe every format Spring MVC's manager maps as the format fallback 9.0 (fix): Spring format negotiation follow-ups: problem+xml ordering, fallback wording Nov 21, 2026

@jamesfredley jamesfredley left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requested changes. A configured problem type is treated as if it were not configured.

boolean problemXmlConfigured = mimeTypes.any { MimeType configured ->
configured?.name?.equalsIgnoreCase(MediaType.APPLICATION_PROBLEM_XML_VALUE)
}
int xml = mediaTypes.findIndexOf { MediaType mediaType ->

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

problem is mapped to application/problem+xml, and it is not also listed as a Grails type. A request accepts that type and then atom. Atom is chosen first. The mapping was explicit. Keep the order the request asked for.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A problem mapping in spring.mvc.contentnegotiation.media-types alone doesn't make application/problem+xml a Grails type. With the setting, configuredFor still reads it as xml through its +xml suffix, and without the setting DefaultAcceptHeaderParser reads it as application/xml. So Grails resolves atom for this header either way, as Grails 8 did. Keeping the header's order here would have Spring MVC write problem+xml while response.format and withFormat say atom. Changing both sides instead would make the setting change the format compared to running without it. Where grails.mime.types names application/problem+xml, the format is problem and the order is kept. f82e6fd adds a test for each case: the Spring-only mapping (atom, with application/atom+xml ahead of application/problem+xml for Spring MVC) and the configured type (problem, header order kept). So I've left 3364f39 as it is.

@matrei matrei left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed at 3364f39 (base 9.0.x, merge base 733397b, the merge of #16996 and the current tip of 9.0.x). 9.0.x is the right base: grails.mime.negotiation.spring exists only there, and preferringSuffixedXml came with #16996 and is in no release yet, so it can stop being static.

What I ran:

  • :grails-mimetypes:test with the build cache off: 206 tests, all pass.
  • The new rows against changes to the code:
    • In springMediaTypesOf, a lookup that keeps the case of the format fails the JSON row, and no fallback at all fails both rows. With grails.mime.types of all and xml, the manager maps only json and xml, so the json row does come from Spring MVC's default.
    • In preferringSuffixedXml, dropping the problem+xml clause fails the new row of SpringFormatNegotiationSpec and FormatNegotiationComparisonSpec.
  • :grails-doc:publishGuide builds (at e7fa993, whose docs 3364f39 leaves as they are), and the changed passages read as intended in single.html.

Only the canary jobs fail, as they do on 9.0.x at 733397b.

To fix

  1. upgrading90x.adoc:1587: "A format that Spring MVC's content negotiation manager maps, such as ... one of the defaults Spring MVC registers for its message converters (json, and xml, ...), whatever its case, decides what Spring MVC writes, ..., while respond still answers 406 for it." The examples now include json and xml, which grails.mime.types lists by default, so the sentence reads as if respond answered ?format=json with 406. The guide ("a format grails.mime.types does not list and ...") and the skill ("A format only ...") keep the scope, and "A format only Spring MVC's content negotiation manager maps" would do it here too.

  2. The guide (contentNegotiation.adoc:309), the upgrade note, the skill and the Javadoc of springMediaTypesOf list what the manager maps as the formats spring.mvc.contentnegotiation.media-types adds and Spring MVC's defaults. My point on #16996, which this follows, got two things wrong:

    • The manager also maps the data formats Grails registers with it as format aliases: json, xml, hal, atom, rss, csv and text, where grails.mime.types lists them (section 15 of the upgrade notes). Since the lookup ignores case, ?format=HAL, ?format=CSV and ?format=Text resolve to application/hal+json, text/csv and text/plain for what Spring MVC writes, while response.format is null, so respond answers 406, as for ?format=JSON. I checked this with temporary features in SpringFormatNegotiationSpec. With the default grails.mime.types, the manager maps atom, csv, hal, json, rss, text and xml.
    • Spring MVC 7.1.0 registers its defaults for the media types its message converters support, not for the libraries on the classpath: WebMvcConfigurationSupport.getDefaultMediaTypes() collects them from getMessageConverters(). It also registers yaml when a converter supports application/atom+xml, a Spring bug with an open fix, spring-projects/spring-framework#37725. So yaml currently comes with Rome rather than with Jackson's YAML module.

    Naming Spring MVC's defaults by example, rather than listing them, would keep the text right as Spring changes them. For the guide, something like: "The manager maps the data formats Grails registers with it, those among json, xml, hal, atom, rss, csv and text that grails.mime.types lists, the formats spring.mvc.contentnegotiation.media-types adds, and those Spring MVC registers for the types its message converters support, such as json. It matches a format whatever its case, which grails.mime.types does not, so ?format=JSON and ?format=HAL are written as application/json and application/hal+json." The upgrade note can point at section 15 for the first part, and the skill and the Javadoc can say the same in short.

  3. 3364f39: no test covers a grails.mime.types that names application/problem+xml. Taking the !problemXmlConfigured out, so that a configured problem+xml counts as the XML type too, fails neither SpringFormatNegotiationSpec nor FormatNegotiationComparisonSpec. A row of SpringFormatNegotiationSpec with such a grails.mime.types would cover it: there Accept: application/problem+xml, application/atom+xml is the problem format, response.mimeTypes is [application/problem+xml, application/atom+xml], and Spring MVC keeps that order.

On the inline comment about an explicit problem mapping

A problem: application/problem+xml mapping in spring.mvc.contentnegotiation.media-types alone does not change the format Grails resolves for Accept: application/problem+xml, application/atom+xml: it is atom, with response.mimeTypes of [application/atom+xml, application/xml], with the setting and without it, and with the setting Spring MVC gets [application/atom+xml, application/problem+xml]. Keeping the order of the header there would have Spring MVC prefer problem+xml while response.format and withFormat answer atom, which is the disagreement preferringSuffixedXml exists to prevent. The check follows DefaultAcceptHeaderParser, which reads problem+xml as application/xml unless a type of grails.mime.types has that name, and where one does, the format is problem and the order is kept (item 3). I checked each of these with temporary features. So I think the commit is right as it is.

Optional

  1. A HAL row in the new feature of e7fa993, with the default grails.mime.types and [application/hal+json] expected, would pin the case of a format Grails registers, if the text names it.

Verified as correct

  • springMediaTypesOf looks the format up in lower case, while mediaTypesOf matches it exactly, as the guide and the Javadoc now say.
  • The new feature of e7fa993 sends Accept: application/xml, which its grails.mime.types lists, so a pass cannot come from the Accept header.
  • The table row of the guide and the Javadoc of GrailsFormatContentNegotiationStrategy give their examples with "such as", so they hold with the fuller list.
  • Spring Framework 7.1.0, which 9.0.x resolves, registers atom, rss, xml, json, smile, cbor and yaml defaults, the formats the PR lists.
  • 3364f39: the configured check matches the one DefaultAcceptHeaderParser makes, a type of that name ignoring case, and FormatNegotiationComparisonSpec shows the Grails formats of the new header now agree under every configuration it compares.

… maps

preferringSuffixedXml takes application/problem+xml as the XML type a
+xml type comes ahead of only where no type of grails.mime.types names
it, as DefaultAcceptHeaderParser reads it. No test covered the configured
case: with grails.mime.types naming application/problem+xml, Accept:
application/problem+xml, application/atom+xml is the problem format and
keeps the order of the header, for Grails and for what Spring MVC writes.
A problem mapping in Spring MVC alone leaves it the atom format, with
application/problem+xml behind atom, as Grails reads it as application/xml.
Grails registers the data formats of grails.mime.types (json, xml, hal,
atom, rss, csv and text) with Spring MVC's content negotiation manager as
format aliases, and the fallback looks a format up there whatever its
case. With the default grails.mime.types, ?format=HAL, ?format=CSV and
?format=Text are written as application/hal+json, text/csv and text/plain
for what Spring MVC writes, while Grails resolves no format for them.
The fallback takes a format grails.mime.types does not list from Spring
MVC's content negotiation manager. Besides the formats
spring.mvc.contentnegotiation.media-types adds, the manager maps the data
formats Grails registers with it (json, xml, hal, atom, rss, csv and text,
where grails.mime.types lists them), which the case-insensitive lookup
also finds as ?format=HAL, and those Spring MVC registers for the types
its message converters support, which depend on the converters, not on
the libraries on the classpath. The guide, the upgrade note, the upgrade
skill and the Javadoc of springMediaTypesOf now say so, naming Spring
MVC's defaults by example.

The upgrade note says "a format only" the manager maps, so it no longer
reads as if respond answered ?format=json with 406, and it links the
format resolution section by a new anchor, upgradingGrailsFormatResolution.
@codeconsole

Copy link
Copy Markdown
Contributor Author

@matrei thanks, all three held, and I added the HAL row too.

  1. f82e6fd adds a test where grails.mime.types names application/problem+xml: Accept: application/problem+xml, application/atom+xml is the problem format, and Grails and Spring MVC both keep the header's order. It fails with !problemXmlConfigured taken out. A second test covers a problem mapping in Spring MVC only, which stays atom.
  2. d86b855 checks that with the default grails.mime.types, ?format=HAL, ?format=CSV and ?format=Text are written as application/hal+json, text/csv and text/plain, while response.format is null.
  3. cea86e4 fixes the wording in the guide, the upgrade note, the skill and the springMediaTypesOf Javadoc. They now say the manager maps the data formats Grails registers with it, the formats media-types adds, and those Spring MVC registers for the types its message converters support, with json as the example and no fixed list. Each names ?format=HAL next to ?format=JSON. The upgrade note says "A format only Spring MVC's content negotiation manager maps", so it no longer reads as if ?format=json got a 406. It links section 15 through a new upgradingGrailsFormatResolution anchor, so the link can't go stale when sections are renumbered.

:grails-mimetypes:test, its codeStyle and :grails-doc:publishGuide pass, and the new link stays on the page in single.html.

@jamesfredley jamesfredley left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requested changes. The format and the written type disagree when the request also accepts plain xml.

int xml = mediaTypes.findIndexOf { MediaType mediaType ->
mediaType.type == 'application' && mediaType.subtype == 'xml' || mediaType.type == 'text' && mediaType.subtype == 'xml'
mediaType.type == 'application' && mediaType.subtype == 'xml' || mediaType.type == 'text' && mediaType.subtype == 'xml' ||
!problemXmlConfigured && mediaType.equalsTypeAndSubtype(MediaType.APPLICATION_PROBLEM_XML)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

problem is mapped only in Spring MVC. A request accepts xml, then atom, then problem+xml. Spring MVC writes problem+xml, but the format is atom, because the type this moved forward then counts as the xml anchor and atom moves ahead of it again. Make the format and the written type the same.

@testlens-app

testlens-app Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

🚨 All tests passed but jobs failed 🚨

Failed Jobs without Test Failures

❌ Groovy Snapshot Canary Build / Build Grails (shard 0)
❌ Groovy Snapshot Canary Build / Build Grails (shard 1)

🏷️ Commit: cea86e4
▶️ Tests: 150213 executed
⚪️ Checks: 97/97 completed

Rerun Controls

Click the checkbox to trigger a rerun:

  • Rerun jobs

Learn more about TestLens at testlens.app/docs.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

3 participants