graphql/graphql-scalars

GraphQL Scalars specifications repo.

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 scalars.graphql.org, 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.

How to contribute

1. Copy the template-string.md template for Custom Scalars based on the built-in String Scalar, or otherwise use the template.md 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.

Review 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.

Immutable 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.

Licensing

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

Contributor 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 [email protected].

Copyright

Copyright © GraphQL contributors

THESE MATERIALS ARE PROVIDED “AS IS”. The parties expressly disclaim any warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to the materials. The entire risk as to implementing or otherwise using the materials is assumed by the implementer and user. IN NO EVENT WILL THE PARTIES BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THIS DELIVERABLE OR ITS GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER MEMBER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Code of Conduct

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

graphql-scalars's Issues

Contribution agreement and license

This being part of the GraphQL foundation I expect that everybody needs to sign the CLA of the foundation before the code can be merged. @leebyron that correct?

Also: which license should be used for the specs?

The GraphQL spec itself states:
This specification was licensed under OWFa 1.0 in 2017. Copyright and trademark was transferred to the GraphQL Foundation in 2019.

I would expect we do the same for custom Scalars specs.

Edit Rights

Something that occurred to me, to discuss: who should we accept edits from (or e.g. new versions of an existing scalar), besides the original author? Other members of a shared org seem obvious, but there's no obvious path for sharing ownership over a single author's scalar.

Not sure if this actually matters, or if we should be encouraging more of a fork-and-evolve model?

URL Proposal

Here's my pitch for how the built URLs could work:

Urls follow a /namespace/scalar/version hierarchy:

• https://scalars.graphql.org/
  • Lists out all scalars plus a search box
• https://scalars.graphql.org/namespace/
  • Lists out all scalars within a namespace.
  • Namespaces are required to be github usernames or orgs so we can render a link that replaces "scalars.graphql.org" with "github.com" and takes you somewhere useful.
• https://scalars.graphql.org/namespace/scalar
  • Metadata about a scalar spec including usage numbers (if we can get those, cdn hits API?) and links to all published versions (similar to https://spec.graphql.org/ ?)
  • Note that the scalar name in a URL is non-normative. It does not affect the name of the scalar found in someone's schema.
• https://scalars.graphql.org/namespace/scalar/vA.B.C
  • Loads a specific version of a scalar spec. This URL is immutable
• https://scalars.graphql.org/namespace/scalar/vA
  • Loads latest version which matches vA.X.X (this could be a 302 redirect)
• https://scalars.graphql.org/namespace/scalar/vA.B
  • Loads latest version which matches vA.B.X (this could be a 302 redirect)

Examples:

• https://scalars.graphql.org/andimarek/datetime/v1.0.0
  • Andi's original datetime proposal
• https://scalars.graphql.org/graphql/url/v2
  • A future official URL scalar type, second version, which include any latest prose edits

Semver rules:

• Major (vA.X.X)
  • Any change which is not backwards compatible with previous scalar specs
  • Example: a serialization format has changed
• Minor (vX.B.X)
  • Any behavioral change which is backwards compatible
  • Example: an input validation rule was made more lenient
• Patch (vX.X.C)
  • Non-behavioral changes
  • Example: Copy edits or additional examples

Implementation:

• Current version is added to the top of the scalar spec markdown file as front-matter
• This is always in the form vA.B to avoid merge conflicts for every PR.
  • The webpage generator should pick the next highest digit to create a vA.B.C from any previous built page if the frontmatter version does not change in a merged PR.
• Part of our template guidelines should include semver guidelines. PRs that include behavioral changes should be encouraged to update the version front-matter as part of their patch.

Example:

---
Name: DateTime
Version: v1.2
Authors: andimarek 
---

# DateTime

...

Requirements Discussion

Ticket for any discussion of what requirements we want to enforce before we accept a scalar definition to the repo. Off the top of my head:

• Conforms with whatever we decided on for URL/namespacing/versioning: #1
• Conforms with whatever rough format we decide on in #2
• Some kind of licensing agreement or contributor's agreement or something something legal? #7

Anything else?

Add LocalDateTime scalar?

Right now we have:

• DateTime, exact point in time with UTC offset: 2011-08-30T13:22:53.108+03:30
• LocalDate, a local date without a time-zone: 1983-10-20

But we're missing a way to represent a local date with a time like 2007-12-03T10:15:30

It cannot be represented as a DateTime because the semantics are different. A LocalDateTime point in time might change if some of our governments decide to change timezones.

The specification could be relatively close to the Java LocalDateTime. I can write something up if there's interest.

Prior art:

• graphql/graphql-spec#579
• graphql-java/graphql-java-extended-scalars#7

Blessing scalars for GraphQL-JS

To discuss: how do we want to bless certain custom scalars for inclusion in graphql-js? Is it just an ad-hoc vote of the working group? Or should we not bless any such scalars, and leave the community to figure it out? There's definitely a case to be made for standard reference implementations of some key ones like DateTime...

Idea: Expand the url/folder structure to include Business Name

I'm super excited about this initiative. Have you thought about allowing businesses to contribute their scalars here? Potentially in a structure like scalars/business_name/author_name.

Regex based custom scalas + automatic discovery

Idea: we could add another custom scalar spec which is a subclass of the string template, which is regex based.

This means the input and output would be fully described with a regex (or two different regex for different input and output).

The main goal of this would be to offer some kind of automatic discovery of the regex. For example via dedicated URL. This would allow tools like GraphiQL to dynamically discover custom scalar specs and validate them and offer code completion.

Example:

spec for LocalDate. The format is "yyyy-mm-dd"

regex for input and output is: "\d{4}-\d{2}-\d{2}".

The patterns for input and output could be reachable via:
scalars.graphql.org/andimarek/local-date/input-regex
scalars.graphql.org/andimarek/local-date/output-regex

Both endpoint would just return HTTP text with "\d{4}-\d{2}-\d{2}". Nothing else.

One implementation detail I am not sure is how we automatically could get the patterns from the template or maybe we just expect contributors to specify them in extra files?

@dondonz @leebyron what do you think? Would love to hear some ideas how to implement this. Maybe spec-md could help here even?