Reconsider repository structure

[glen-84]

I find it odd that:

1. The structure encourages users to "create their own version" of a scalar if they disagree with something.

   Shouldn't the official GraphQL Scalars repository encourage the opposite – a single canonical definition of each scalar, that all or most implementers agree on?

   How will we benefit from glen/date-time, andreas/date-time, martin/date-time, etc.? And why do I need this repository if I could just host my spec under a personal or business URL?

2. Contributor names are included in the spec URLs.

   IMO, the URLs should have the format:

   https://scalars.graphql.org/date-time

   This could be extended with a version number when changes are made:

   https://scalars.graphql.org/date-time/v2

   It feels off including usernames in spec URLs.

   Related: Allow versioning the scalar urls #34.

[martinbonnin]

My 2 cents: I agree in theory, I pragmatically disagree.

GraphQL, as an org, is moving slow. @oneOf took multiple years. Semantic nullability has been ongoing for 5 years now. This is for good reasons because most of the choices are hard to undo (type 1 decisions).

But if you look inside the graphql-spec repo, you will also find a lot of abandonned pull requests, just because their authors gave up. This is creating frustration and overall hurting the ecosystem IMO.

By adding the name of the scalars in the url, we unlock users who want to use something fast.

And why do I need this repository if I could just host my spec under a personal or business URL?

You get feedback from the community and your scalar becomes more discoverable.

Proposal: graphql scalars

What about we keep the existing scheme but we also add a graphql section with the "officially endorsed" scalars? We can iterate quickly on personal scalars. If some of them get some traction, they get promoted to "officially endorsed"/"recommended" one. Then we get the best of both worlds?

[glen-84]

GraphQL, as an org, is moving slow.

So is this repository. 😄

It's not exactly an auto-merge scenario here – almost 3 years have passed, and there are 2 scalars, both authored by Andi.

You get feedback from the community and your scalar becomes more discoverable.

Feedback which you can ignore, because you decide what goes in. Am I motivated to provide feedback on something when I know that the author will just make a decision that suits them, versus working toward a consensus?

The specified-by URL provides most of the discovery – if these are "personal" scalars that solve a problem for a specific user or organization, then discovery has little value.

What about we keep the existing scheme but we also add a graphql section with the "officially endorsed" scalars?

It would certainly be an improvement, although I'm not sure how we would determine traction. Also, iteration would require versioning, and date-time-2 doesn't look great IMO. 🙂

[martinbonnin]

So #22 repository. 😄
It's not exactly an auto-merge scenario here – almost 3 years have passed, and there are 2 scalars, both authored by Andi.

I agree 100%. This repo has been moving slow. But this is not inevitable. This repo is a good test bed for new processes because the stakes are lower than in the main repo. I think we can make it move much much faster. I have added this item to the December working group meeting

Am I motivated to provide feedback on something when I know that the author will just make a decision that suits them, versus working toward a consensus?

The author decision also contributes the consensus. Same for your feedback, it's all recorded. People give feedback on the internet all the time. That will be true here as well.

iteration would require versioning, and date-time-2 doesn't look great IMO.

Iteration would happen quickly using personal scalars. We can start with yours. chillicream/LocalDateTime is getting some eyeballs right now. You can use it in ChilliCream, I would use it in Apollo Kotlin, etc... 6 months from now, if we're happy with it, we make a proposal to move it to graphql/LocalDateTime. I would expect that will trigger discussions such as "let's include all the other date formats and make them consistent". This will take another few months or more, depending if there is a champion or not. If we have a champion, we can probably get a consensus-based, recommended graphql/LocalDateTime in 2026.

That consensus-driving is a lot of effort that contributors always under estimate and end up frustrated with. This is what I like about per-user scalars. We can move forward without having that champion.

[andimarek]

Some hard earned lesson: you will not be able to define standard scalars for date time or others.

This ship has sailed and everybody has in detail different expectations and opinions.

This repo provides the opportunity to have your scalar spec hosted for free forever. So if you want to define your own spec for yourself or for your company or for the good of the community your are encouraged to do so.

But you certainly don't have to: the specified by part of a custom scalar is independently of this repo.

That being said: I hoped for more traction after we started this project. Maybe we didn't marketed it good enough or maybe writing a custom scalar spec is still too hard or maybe custom scalars simply don't need a well defined spec in most cases.

The original need for custom scalars came from my work at a distributed/federated gateway: you need a clearly defined spec for custom Scalars shared across subgraphs imho. But so far this pain was not felt by enough people to move the needle in this project.

[martinbonnin]

you will not be able to define standard scalars for date time or others.
if you want to define your own spec for yourself or for your company

I think there's a 3rd option:

1. standard scalars for dates are impossible
2. users can have their own personal scalars
3. the GraphQL community (us) can hand-pick a few high-quality personal scalars and promote them to "recommended" custom scalars.

Recommended custom scalars are not in the main spec. You still need to add @specifiedBy() to them in your schema. But you get the warm fuzzy feeling that it is endorsed by most community members because they are in the graphql namespace.

[glen-84]

you will not be able to define standard scalars for date time

standard scalars for dates are impossible

How so? Most people would agree on RFC 3339 for DateTime, and something similar for local variants.

The standard exists – the main issue is when you start diverging from that standard without very strong reasons, and then every one of those decisions has to be discussed at length, as seen with fractional seconds. If DateTime simply referred to RFC 3339 with some information on coercion (if necessary), then there wouldn't be much room for subjectivity. If the standard doesn't enforce the number of fractional seconds, did we really need to do that (for example)?

[martinbonnin]

Good questions for which I don't have the answer :)
Another thing is also that it's too late now. There's no way we can add LocalDateTime to the main GraphQL spec without breaking a bunch of schemas out there.

Closest we can do is __LocalDateTime...

[glen-84]

I'm not suggesting that it be added to the main spec, I'm only suggesting a set of canonical scalars based on frequently adopted standards like RFC 3339, with little or no variations.

[glen-84]

FWIW, JSON Schema simply references RFC 3339:

https://json-schema.org/understanding-json-schema/reference/type#built-in-formats

[andimarek]

I went through this a couple of years back and tried to define a standard date time scalar.

You can't because there are already to many out there and people can't agree on the details.

You also can't simply refer to rfc 3339, if you want to have well defined behavior, because it is ambiguous. All the details why it is amnigious is in my date time scalar spec 😀.

You can see already in the other PR how @martinbonnin and I disagree about some details and I think nobody is objectively right or wrong.

If you want to have stronger standards than what this repo offers I suggest to propose so in the main GraphQL WG.

We cant just change how this repo is organized and structured without a larger decision from the WG.

[glen-84]

You also can't simply refer to rfc 3339

JSON Schema does this. I don't really see the ambiguity, and if it does exist, it should be resolved in the RFC, in my opinion.

Anyway, I have no objection to this being discussed by the WG. 🙂

[martinbonnin]

@glen-84 assuming we go the JSON schema road (it doesn't seem ambiguous to me either), what would you recommend?

1. all servers and clients must support arbitrary precision dates.
2. on precision loss, a server/client must throw an error.
3. on precision loss, a server/client must round (what is the algorithm for rounding?)

[andimarek]

@martinbonnin you state that RFC 3339 is not ambiguous and then proceed to ask clarifying questions ... is that not a contradiction?

[martinbonnin]

@andimarek I don't think it's a contradiction. RFC 3339 is very clear that it supports arbitrary precision dates.

GraphQL, as a pragmatic language, might make a different choice to ease implementation. That doesn't make RFC 3339 ambiguous.