Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

RFC: Define custom scalars in terms of built-in scalars. #1552

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

IvanGoncharov
Copy link
Member

As @leebyron suggested during last WG I'm adopting #914 and rebasing it on top of current master.

Here is the original description:

This proposes an additive change which allows custom scalars to be defined in terms of the built-in scalars. The motivation is for client-side code generators to understand how to map between the GraphQL type system and a native type system. As an example, a URL custom type may be defined in terms of the built-in scalar String. It could define additional serialization and parsing logic, however client tools can know to treat URL values as String. Presently, we do this by defining these mappings manually on the client, which is difficult to scale, or by giving up and making no assumptions of how the custom types serialize.

Another real use case of giving client tools this information is GraphiQL: this change will allow GraphiQL to show more useful errors when a literal of an incorrect kind is provided to a custom scalar. Currently GraphiQL simply accepts all values.

To accomplish this, this proposes adding the following:

  • A new property when defining GraphQLScalarType (ofType) which asserts that only built-in scalar types are provided.

  • A second type coercion to guarantee to a client that the serialized values match the ofType.

  • Delegating the parseLiteral and parseValue functions to those in ofType (this enables downstream validation / GraphiQL features)

  • Exposing ofType in the introspection system, and consuming that introspection in buildClientSchema.

  • Adding optional syntax to the SDL, and consuming that in buildASTSchema and extendSchema as well as in schemaPrinter.

  • Adding a case to findBreakingChanges which looks for a scalar's ofType changing.

This proposes an additive change which allows custom scalars to be defined in terms of the built-in scalars. The motivation is for client-side code generators to understand how to map between the GraphQL type system and a native type system. As an example, a `URL` custom type may be defined in terms of the built-in scalar `String`. It could define additional serialization and parsing logic, however client tools can know to treat `URL` values as `String`. Presently, we do this by defining these mappings manually on the client, which is difficult to scale, or by giving up and making no assumptions of how the custom types serialize.

Another real use case of giving client tools this information is GraphiQL: this change will allow GraphiQL to show more useful errors when a literal of an incorrect kind is provided to a custom scalar. Currently GraphiQL simply accepts all values.

To accomplish this, this proposes adding the following:

* A new property when defining `GraphQLScalarType` (`ofType`) which asserts that only built-in scalar types are provided.

* A second type coercion to guarantee to a client that the serialized values match the `ofType`.

* Delegating the `parseLiteral` and `parseValue` functions to those in `ofType` (this enables downstream validation / GraphiQL features)

* Exposing `ofType` in the introspection system, and consuming that introspection in `buildClientSchema`.

* Adding optional syntax to the SDL, and consuming that in `buildASTSchema` and `extendSchema` as well as in `schemaPrinter`.

* Adding a case to `findBreakingChanges` which looks for a scalar's ofType changing.
@IvanGoncharov IvanGoncharov added the spec RFC Implementation of a proposed change to the GraphQL specification label Oct 14, 2018
Base automatically changed from master to main January 27, 2021 11:10
@IvanGoncharov IvanGoncharov added this to the post-16.0.0 milestone Aug 11, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
CLA Signed spec RFC Implementation of a proposed change to the GraphQL specification
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants