Better describe what Coercing.valueToLiteral is for

[ummels]

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?

[bbakerman]

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.

[dondonz]

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.

valueToLiteral in 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:

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.