You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Better describe what Coercing.valueToLiteral is for #3558
While upgrading to GraphQL Java 21, I stumbled over the method valueToLiteral offered by the Coercing interface. So far, when implementing a custom scalar, I haven't bothered about implementing this method and have not encountered any problems so far although the default implementation throws an exception.
In the JavaDoc of the Coercing interface, it says that "every valid external input values for parseValue(Object) is also valid for valueToLiteral(Object) and vice versa" which suggest that the argument to valueToLiteral should be in serialized form. However, when looking at implementations of this method, I see that most often serialze is called first on the argument, which suggests otherwise.
Could you please improve the JavaDoc and also the documentation on custom scalars, which does not mention this method at all?
I agree this is poorly documented and could be improved.
The reason your not having any problems is that this valueToLiteral method is not called by the main graphql-java engine code path. Rather its only called via graphql.execution.ValuesResolver#getNormalizedVariableValues which is a relatively new mechanism and as I said not used by the engine.
I also agree it could be better! Thanks for the feedback
I do want to rewrite the GraphQL Java docs to make it easier to understand what's going on. In the meantime, @andimarek and I did write a specification page for the GraphQL Scalars project https://scalars.graphql.org/implementation-guide.html. This explains how the coercion methods work together, but we didn't use the same method names in the spec as we do in GraphQL Java. Also another downside, this spec is dense and not an easy read. I would be looking to write a much more easier to read version for the GraphQL Java docs.
It is used when a literal representation of a raw input value is required. For example the default value for a field in an Introspection response. If a GraphQL implementation doesn’t provide a way to define a raw input value programmatically, rawInputValueToLiteral might not be needed.
You're correct that serialize is the method to look at for serialization, not valueToLiteral.
Hi @dondonz, I noticed the claude/fix-3558-coercing-valueToLiteral-docs branch from April that never became a PR. I have a version based on current master that also lists exactly when the engine calls valueToLiteral (external-state values via defaultValueProgrammatic/valueProgrammatic during schema printing, introspection and validation, plus normalized variables), explains when it's safe not to implement it, and adds a Spock test pinning that behaviour. Happy to open a PR if that's useful, or to leave it if you'd rather finish yours.
Activity
bbakerman commentedon Apr 9, 2024
I agree this is poorly documented and could be improved.
The reason your not having any problems is that this valueToLiteral method is not called by the main graphql-java engine code path. Rather its only called via
graphql.execution.ValuesResolver#getNormalizedVariableValueswhich is a relatively new mechanism and as I said not used by the engine.dondonz commentedon Apr 9, 2024
I also agree it could be better! Thanks for the feedback
I do want to rewrite the GraphQL Java docs to make it easier to understand what's going on. In the meantime, @andimarek and I did write a specification page for the GraphQL Scalars project https://scalars.graphql.org/implementation-guide.html. This explains how the coercion methods work together, but we didn't use the same method names in the spec as we do in GraphQL Java. Also another downside, this spec is dense and not an easy read. I would be looking to write a much more easier to read version for the GraphQL Java docs.
valueToLiteralin GraphQL Java is what we call "Raw input value to literal" in the spec https://scalars.graphql.org/implementation-guide.html#sec-Raw-Input-Value-to-Literal. As @bbakerman said it's very rarely used. From the page:You're correct that
serializeis the method to look at for serialization, notvalueToLiteral.docs: clarify Coercing.valueToLiteral JavaDoc
idsoke commentedon Nov 14, 2026
Hi @dondonz, I noticed the
claude/fix-3558-coercing-valueToLiteral-docsbranch from April that never became a PR. I have a version based on current master that also lists exactly when the engine callsvalueToLiteral(external-state values viadefaultValueProgrammatic/valueProgrammaticduring schema printing, introspection and validation, plus normalized variables), explains when it's safe not to implement it, and adds a Spock test pinning that behaviour. Happy to open a PR if that's useful, or to leave it if you'd rather finish yours.andimarek commentedon Nov 14, 2026
Hi @idsoke ... please do, thanks a lot
Clarify what Coercing.valueToLiteral receives and when it is called