Skip to content

Clarify what Coercing.valueToLiteral receives and when it is called - #4561

Merged
bbakerman merged 2 commits into
graphql-java:masterfrom
idsoke:coercing-valueToLiteral-docs
Nov 15, 2026
Merged

bbakerman merged 2 commits into
graphql-java:masterfrom
idsoke:coercing-valueToLiteral-docs

Conversation

@idsoke

@idsoke idsoke commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #3558

The Coercing Javadoc did not say whether valueToLiteral gets an external or an internal value, or when graphql-java actually calls it, so scalar authors could not tell whether they need to implement it.

This PR:

  • Documents the three forms of an input value (external, internal, literal) with a date time example.
  • States that valueToLiteral receives an external value (the same kind parseValue accepts), not an internal value or the result of serialize.
  • Lists the cases that call it:
    • printing (SchemaPrinter), introspection and validation of external-state values set via defaultValueProgrammatic(Object) or valueProgrammatic(Object) on applied directive arguments
    • normalized variables (ValuesResolver#getNormalizedVariableValues)
  • Notes that defaultValueLiteral(Value) and the deprecated defaultValue(Object) don't go through it, so schemas that only use those never hit the default UnsupportedOperationException.
  • Adds a test in CoercingTest that pins this behaviour.

As discussed in #3558 (comment). The earlier comment that it is only called via getNormalizedVariableValues is no longer accurate, which the new test shows.

Ran ./gradlew test --tests graphql.schema.CoercingTest: 6 tests, 0 failures.

The Javadoc did not say whether valueToLiteral gets an external or an
internal value, and did not say when graphql-java calls it, so scalar
authors could not tell whether they need to implement it.

Document the external, internal and literal forms, state that
valueToLiteral receives an external value (not a serialized one), and
list the cases that call it: printing, introspection and validation of
programmatic default and applied directive values, and normalized
variables. Add a test that pins this behaviour.

Fixes graphql-java#3558

@bbakerman bbakerman left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Thanks

@bbakerman
bbakerman enabled auto-merge November 15, 2026 22:47
@github-actions

Copy link
Copy Markdown
Contributor

Test Report

Test Results

Java Version Total Passed Failed Errors Skipped
Java 17 6370 (+1 🟢) 6315 (+1 🟢) 0 (±0) 0 (±0) 55 (±0)
Java 21 6370 (+1 🟢) 6315 (+1 🟢) 0 (±0) 0 (±0) 55 (±0)
Java 25 6370 (+1 🟢) 6315 (+1 🟢) 0 (±0) 0 (±0) 55 (±0)
jcstress 32 (±0) 32 (±0) 0 (±0) 0 (±0) 0 (±0)
Total 19142 (+3 🟢) 18977 (+3 🟢) 0 (±0) 0 (±0) 165 (±0)

Code Coverage (Java 25)

Metric Covered Missed Coverage vs Master
Lines 26783 2698 90.8% ±0.0%
Branches 7681 1170 86.8% ±0.0%
Methods 7414 1091 87.2% ±0.0%

No per-class coverage changes detected.

Full HTML report: build artifact jacoco-html-report

Updated: 2026-11-15 22:55:35 UTC

@bbakerman
bbakerman merged commit f5a8114 into graphql-java:master Nov 15, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Better describe what Coercing.valueToLiteral is for

2 participants