1/14/2023 by Andreas Marek, Donna Zhou
You are welcome to contribute custom scalar specifications (abbreviated as "specs"). Once your spec is merged in, it will be hosted at
scalars.graphql.org/<GitHub-username>/<specification-name>. See how to contribute on the contribution guide.
scalar DateTime@specifiedBy(url: "https://scalars.graphql.org/andimarek/date-time")
Custom scalars have been part of the GraphQL spec since day one. They have the unique ability to extend the GraphQL type system with custom types. While custom scalars are powerful, they were more like a black box for the consumers of the API.
Originally, it was very hard for consumers to understand custom scalars as a GraphQL schema did not provide any information apart from its name. For example, it was difficult to understand the exact format of a
DateTime custom scalar. It was also difficult to know whether the
DateTime custom scalar in API A was exactly the same as the
DateTime in API B.
We added the built-in
@specifiedBy directive some time ago, which assigns a URL for the spec of a custom scalar. This provides a standard way to document custom scalars. The
@specifiedBy directive is also introspectable.
However, we have since learned that this was not enough. The burden of writing a custom scalar specs and hosting them was left for each API itself to solve.
With the custom scalar spec project, we provide templates for writing custom scalar specs and also host the specs at a GraphQL Foundation owned domain scalars.graphql.org. This greatly reduces the effort to clearly document and share your custom scalar specs.
Our hope is that this enables an ecosystem of clearly documented custom scalars and eliminates the need to reinvent popular ones again and again. Ultimately, a popular enough custom scalar will be practically indistinguishable from the built-in ones and elevate the GraphQL type system.
See how to contribute a custom scalar spec on the contribution guide.
If you have any comments or questions, please open an issue on the graphql-scalars GitHub repository.