GraphQL Custom Scalars Specification Contribution Guide

Thanks for contributing to GraphQL Scalars.

The goal of the GraphQL Scalars project is to provide a directory of GraphQL Custom Scalar specifications, contributed by the community. Contributed specifications are hosted on a GraphQL Foundation owned domain, which can be referenced with the built-in @specifiedBy GraphQL directive.

GraphQL Custom Scalar specifications are language agnostic and thus can be used to document and standardize behavior across different languages.

Please ensure that you read the Code of Conduct before contributing to this project.

1How to contribute

  1. Copy the template for Custom Scalars based on the built-in String Scalar, or otherwise use the template for all other Custom Scalars. Templates are located in the graphql-scalars GitHub repository.
  2. Modify your selected template, and save it in the correct place scalars/contributed/<github-user-name>/<scalar-name>.md in the graphql-scalars GitHub repository. The directory location is important, as this will form part of the reference URL for your specification.
  3. Install dependencies with npm install and the run npm run build to locally build the resulting public specification files. Navigate to the /public folder to view the built files.
  4. Run npm test to ensure proper formatting before submitting a pull request.
  5. Open a new pull request for each Custom Scalar specification you would like to add.

1.1Review process

Your specification pull request will be reviewed by a maintainer of the graphql-scalars repository. The maintainers will verify that the template has been completed, but note that the correctness of the specification is the responsibility of the original contributor.

1.2Immutable specifications

Specification semantics must not change, as specifications are publicly available reference documents. We will permit small edits which do not change specification semantics, such as typo fixes.

A new version of a Custom Scalar specification should have a new scalar name, either with a number appended such as <scalar-name>2, or a different name such as OffsetDateTime to differentiate from DateTime.


Specifications contributed to the GraphQL Scalars repository are part of the GraphQL Specification Project and are made available by the Joint Development Foundation. The current GraphQL Working Group charter, which includes the IP policy governing all working group deliverables (including specifications, source code, and datasets) may be found in the technical charter.

By contributing to this repository, you agree to license your work according to the licenses governing GraphQL Specification Project deliverables, which are:

Deliverable License
Specifications Open Web Foundation Agreement 1.0 (Patent and Copyright Grants)
Source code MIT License
Data sets CC0 1.0

2.1Contributor License Agreement

This repository is managed by EasyCLA. Project participants must sign the free GraphQL Specification Membership agreement before making a contribution. You only need to do this one time, and it can be signed by individual contributors or their employers.

To initiate the signature process please open a PR against this repo. The EasyCLA bot will block the merge if we still need a membership agreement from you.

You can find detailed information here. If you have issues, please email

3Code of Conduct

This project abides by the GraphQL Foundation’s Code of Conduct.

  1. 1How to contribute
    1. 1.1Review process
    2. 1.2Immutable specifications
  2. 2Licensing
    1. 2.1Contributor License Agreement
    2. 2.2Copyright
  3. 3Code of Conduct