Skip to content

Better describe what Coercing.valueToLiteral is for #3558

Closed

Description

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

Activity

  1. bbakerman commented on Apr 9, 2024

    @bbakerman
    Member

    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.

  2. dondonz commented on Apr 9, 2024

    @dondonz
    Member

    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.

  3. added
    keep-openTells Stale Bot to keep PRs and issues open
    on Jun 4, 2024
  4. added a commit that references this issue on Apr 3, 2026
    7f88193
  5. idsoke commented on Nov 14, 2026

    @idsoke
    Contributor

    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.

  6. andimarek commented on Nov 14, 2026

    @andimarek
    Member

    Hi @idsoke ... please do, thanks a lot

  7. added a commit that references this issue on Nov 14, 2026
    932eb60
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    keep-openTells Stale Bot to keep PRs and issues open

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions