Skip to content

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

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

codeconsole wants to merge 7 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 one of the XML types 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 an XML type too, for the Grails formats and for what Spring MVC writes for a request a URL mapping handles.

As in DefaultAcceptHeaderParser, such a problem type is one of the XML types: a +xml type comes ahead of it, but it is never moved ahead of another XML type itself. Accept: application/xml, application/atom+xml, application/problem+xml is atom, and Spring MVC writes application/atom+xml, as does the upgrade note's text/xml, application/atom+xml, application/problem+xml.

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.

The format and the type Spring MVC writes agree for a repeated +xml type

For a request a URL mapping handles, the +xml preference runs twice: once for what Spring MVC writes and once when Grails resolves its formats. As #16996 brought it in, it took each +xml type behind the XML type out of the list as the first equal type, so where the header repeats a type it removed the copy ahead of the XML type, and the second pass reordered again. With the default grails.mime.types, Accept: application/atom+xml, application/xml, application/atom+xml had Spring MVC write application/xml while the format was atom, and application/xml, application/atom+xml, application/atom+xml was the xml format. Each type is now moved from its own place, so after one pass no +xml type of the quality of the XML type is left behind it, a second pass changes nothing, and both headers are atom, with Spring MVC writing application/atom+xml.

Tests of the +xml preference

SpringFormatNegotiationSpec covers the problem type at equal and at lower quality, with problem+xml configured in grails.mime.types, and with it mapped in Spring MVC only. In the second case each of these headers has the same format and written type: application/problem+xml, application/atom+xml, application/xml, application/atom+xml, application/problem+xml, text/xml, application/atom+xml, application/problem+xml, application/xml, application/problem+xml, application/problem+xml, application/xml, application/atom+xml, application/atom+xml, application/problem+xml, application/atom+xml and application/problem+xml, application/atom+xml, application/atom+xml. The repeated type is also covered with the default types. FormatNegotiationComparisonSpec sends application/problem+xml, application/atom+xml, application/xml, application/atom+xml, application/problem+xml and application/atom+xml, application/xml, application/atom+xml under every configuration it compares: the Grails formats agree, and only what Spring MVC writes differs, as it already does for application/xml, application/atom+xml. The problem type was found while flipping the default for Grails 10, where WithFormatSpec's Grails 8 feature for application/problem+xml, application/atom+xml 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, as do the negotiation specs of grails-test-suite-web and grails-xml.

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.

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

For a request a URL mapping handles, preferringSuffixedXml runs once for
what Spring MVC writes and again when Grails resolves its formats. An
unconfigured application/problem+xml was both a +xml type the first pass
moved ahead of application/xml and the XML type the second pass anchored
on, so Accept: application/xml, application/atom+xml,
application/problem+xml had Spring MVC write problem+xml while the format
was atom.

DefaultAcceptHeaderParser reads such a problem type as application/xml,
one of the XML types, which the +xml preference never moves. Treat it the
same way: it is still the XML type a +xml type comes ahead of, but it is
not moved itself, so a second pass changes nothing and Spring MVC writes
application/atom+xml for that header, the atom format. The Spring-only
problem feature of SpringFormatNegotiationSpec becomes data-driven over
that header, the upgrade note's text/xml example, application/xml,
application/problem+xml and problem+xml between xml and atom, and
FormatNegotiationComparisonSpec sends the header under every
configuration, where only what Spring MVC writes differs.

@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 repeated type in the accept header still makes the written type and the format disagree.

preferringSuffixedXml took each +xml type behind the XML type out of the
list with remove(Object), which removes the first equal type. Where the
header lists a type twice, that was the one ahead of the XML type, so the
first pass, which decides what Spring MVC writes, left the type behind it,
and the second, when Grails resolves its formats, moved it again: with the
default grails.mime.types, Accept: application/atom+xml, application/xml,
application/atom+xml had Spring MVC write application/xml while the format
was atom, and application/xml, application/atom+xml, application/atom+xml
was the xml format. With problem+xml mapped in Spring MVC only, the same
happened with an unconfigured problem+xml as the XML type. apache#16996 brought
the method in on 9.0.x.

Each type is now removed from its own index. After one pass no +xml type
of the quality of the XML type is left behind it, so a second pass changes
nothing, and the format and the type Spring MVC writes agree.
SpringFormatNegotiationSpec covers the repeated type with the default
types and with the Spring-only problem mapping, and
FormatNegotiationComparisonSpec sends application/atom+xml,
application/xml, application/atom+xml under every configuration, where
only what Spring MVC writes differs.
@testlens-app

testlens-app Bot commented Nov 22, 2026 •

Copy link
Copy Markdown

🚨 TestLens detected 1 failed test 🚨

Failed Jobs without Test Failures

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

Test Summary

Tip

Inspect all details with the TestLens CLI: testlens pr 17102

CI / Build Grails-Core (macOS JDK 21) > :grails-async-groovy-concurrent:test

Test Runs Flakiness
AwaitablePromiseFactorySpec > single and aggregate error callbacks receive the same original failure > single and aggregate error callbacks receive the same original failure [checked: true, #1] ❌ 0% 🟢

🏷️ Commit: 26fb584
▶️ Tests: 149993 executed
⚪️ Checks: 97/97 completed

Test Failures

AwaitablePromiseFactorySpec > single and aggregate error callbacks receive the same original failure > single and aggregate error callbacks receive the same original failure [checked: true, #1] (:grails-async-groovy-concurrent:test in CI / Build Grails-Core (macOS JDK 21))
Condition not satisfied:

single.is(original)
|      |  |
null   |  java.io.IOException: outer
       |  	at org.grails.async.factory.groovy.AwaitablePromiseFactorySpec.$spock_feature_0_21(AwaitablePromiseFactorySpec.groovy:346)
       false

	at org.grails.async.factory.groovy.AwaitablePromiseFactorySpec.single and aggregate error callbacks receive the same original failure(AwaitablePromiseFactorySpec.groovy:361)

Rerun Controls

Select tests to mute in this pull request:

  • AwaitablePromiseFactorySpec > single and aggregate error callbacks receive the same original failure

Reuse successful test results:

  • ♻️ Only rerun the tests that failed or were muted before

Click the checkbox to trigger a rerun:

  • Rerun jobs

Learn more about TestLens at testlens.app/docs.

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

The items this review found have been addressed. A repeated type is removed from its own place, so the written type and the format agree.

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