[RFC] Custom Scalar Specification URLs #649

eapache · 2019-11-20T19:48:33Z

This PR contains the specification changes needed for #635.

sungam3r · 2019-11-20T20:29:43Z

Relates to #633

sungam3r · 2019-11-20T20:40:10Z

spec/Section 4 -- Introspection.md

@@ -146,6 +146,9 @@ type __Type {

  # should be non-null for NON_NULL and LIST only, must be null for the others
  ofType: __Type
+
+  # should be non-null for SCALAR only, must be null for the others
+  specifiedBy: String


It correlates to some extent with #300 .
If this extension of the introspection schema will be added, it is logical to expect that the proposed in #300 extension
should be also accepted. Now there is a second server directive besides @deprecated, which is provided through introspection as a special property. I have nothing against this, but I believe that we need to provide a way to get user directives through introspection too. It will be a consistent step.

@sungam3r there are some experiments on introspection extensions. Technically you can already today extend introspection but this alway comes with the danger that you violate a future specification.

@IvanGoncharov was experimenting on this one with GraphQL-js. At the moment you can put metadata on almost everything there. We do almost the same with hot chocolate. The next thing would be to allow to have something like extensions on introspection so that there is a point where you can cleanly extend the introspection types.

Doing this through directives brings some challenges since directives, specifically their arguments are input types that could bear challenges to automatically extend the introspection from those.

@IvanGoncharov maybe we should start a new discussion on that?

I have a separate graphql-dotnet branch in which directives are already returned via introspection. We use this forked preview version in production.

this alway comes with the danger that you violate a future specification.

I agree. It’s not scary for us. We need new features now, and not when they (possibly) appear in the specification.

@sungam3r i did mean that more from them perspective. Hc allows extending the introspection already for a couple of versions. But the user that does that has to know that he/she might violate a future spec. We just have a warning in the docs that you can do it but may run into an issue in the future.

andimarek · 2019-11-20T22:01:59Z

spec/Section 3 -- Type System.md

 ```graphql example
-scalar Time
-scalar Url
+scalar Time @specified(by: "https://tools.ietf.org/html/rfc3339")


This is a bit "misleading" example because RFC3339 is normally used to describe date and time.
How about scalar DateTime @specified(by: "https://example.com/myDateTime") ?

Using a non RFC link would also make it more clear that it is totally fine to come up with your scalar spec.

I think we all agreed to have a specific spec for datetime since it is based on the rfc but more narrow in its implementation. There should be a specific document outlining the rules for this one.

Yeah, I might just take this out as an example until we have something more useful to link to.

Actually, if I take it out it gets even more confusing because the other example to talk about in the paragraph above is URL and then it gets really hard to parse whether I'm talking about the URL scalar as an example, or the URL that you provide in the example to link to the specification.

I'll rename this to DateTime for now, with the expectation that when Andi's restricted datetime scalar format doc gets published we'll change the link to that.

andimarek · 2019-11-20T22:03:23Z

spec/Section 4 -- Introspection.md

@@ -232,13 +235,16 @@ actually valid. These kinds are listed in the `__TypeKind` enumeration.

 Represents scalar types such as Int, String, and Boolean. Scalars cannot have fields.

-A GraphQL type designer should describe the data format and scalar coercion
-rules in the description field of any scalar.
+A GraphQL type designer should provide use the `@specified` directive to provide


typo: should use the

andimarek · 2019-11-20T22:05:38Z

great work @eapache

leebyron · 2019-12-05T16:58:01Z

spec/Section 3 -- Type System.md

@@ -343,9 +343,17 @@ client-specific primitive for time. Another example of a potentially useful
 custom scalar is `Url`, which serializes as a string, but is guaranteed by
 the server to be a valid URL.

+When defining an additional scalar, GraphQL systems should use the `@specified`
+directive to provide an RFC3986-compliant URI pointing to a human-readable


I think throughout we can replace RFC3986-compliant URI with just URL

RFC3986-compliant URI could be understood to include an ISBN for an academic paper or something like that, and the goal here is that a person can load this URL in a browser and go read the spec. URL is well understood with a single definition, so there's no need to qualify it further with which IETF RFC you're referring to.

This in an implementation for a spec proposal: * Spec proposal: [[RFC] Custom Scalar Specification URIs](graphql/graphql-spec#649) * Original issue: [[RFC] Custom Scalar Specification URIs](graphql/graphql-spec#635) Please let me know if I forgot something.

This in an implementation for a spec proposal: * Spec proposal: [[RFC] Custom Scalar Specification URIs](graphql/graphql-spec#649) * Original issue: [[RFC] Custom Scalar Specification URIs](graphql/graphql-spec#635)

m14t · 2019-12-07T00:45:30Z

spec/Section 4 -- Introspection.md

@@ -146,6 +146,9 @@ type __Type {

  # should be non-null for NON_NULL and LIST only, must be null for the others
  ofType: __Type
+
+  # should be non-null for SCALAR only, must be null for the others


Nitpick: Currently in my draft for the reference implementation graphql/graphql-js#2276, if you don't add the @specified directive to a scalar, specifiedBy will be null.

If that's the correct implementation, then perhaps this wording could be updated to something along the lines of:

Suggested change

# should be non-null for SCALAR only, must be null for the others

# should be a string or null for SCALAR only, must be null for the others

Hmm, it's a good point but I think I'd prefer just replacing should with can or may.

eapache · 2019-12-10T19:02:06Z

spec/Section 3 -- Type System.md

-scalar Time
-scalar Url
+scalar UUID @specified(by: "https://tools.ietf.org/html/rfc4122")
+scalar URL @specified(by: "https://tools.ietf.org/html/rfc3986")


@leebyron I changed the capitalization here from Url to URL because Uuid looked particularly gross, and the built-in is already ID not Id. It's a minor editorial thing but it's not really related to this RFC so I wanted to make sure it was ok.

Seems totally fine to me

IvanGoncharov · 2019-12-11T06:53:51Z

spec/Section 4 -- Introspection.md


 Fields

 * `kind` must return `__TypeKind.SCALAR`.
 * `name` must return a String.
+* `specifiedBy` may return a URL or {null}.


We don't have a URL type so it should be String.

maybe may return a String (in the form of a URL) or {null}. ?

IvanGoncharov · 2019-12-15T16:54:32Z

@eapache bikeshedding: How about changing @specified(by: 'http://example.com') to @specifiedBy(url: 'http://example.com')
Pros:

Fewer chances to conflict with existing and previous directives
It's easier to figure out that you pass/get URL from the name, e.g. inside introspection we would have specifiedByURL instead of specifiedBy

sungam3r · 2019-12-15T19:44:12Z

+1 for @specifiedBy(url: 'http://example.com')
-1 for specifiedByURL

This is a personal feelings, specifiedByURL causes some associations with the Hungarian notation, which has its drawbacks.

eapache · 2019-12-16T15:47:44Z

I'm weakly in favour of @specifiedBy(url:) instead of @specified(by:).

m14t · 2019-12-30T22:19:11Z

spec/Section 3 -- Type System.md

+relevant IETF specifications.
+
+```graphql example
+scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122")


While implementing this in graphql/graphql-js#2276 @IvanGoncharov provided the following comment:

If at some point we decide to add UUID scalar into this library it would be a confusing example.
It's better to use some abstract scalar like Foo and https://example.com/foo_spec.

Question: Do we want to make that same change here as well? If so this likely applies to URL as well, and effects a few locations in this PR.

Point taken that it could become confusing, but it's not confusing yet, and there is definitely value in having a concrete example that lines up with use cases a lot of actual developers will run into. I'm planning to leave this as is, and we can change it if becomes an issue later.

spec/Section 3 -- Type System.md

This in an implementation for a spec proposal: * Spec proposal: [[RFC] Custom Scalar Specification URIs](graphql/graphql-spec#649) * Original issue: [[RFC] Custom Scalar Specification URIs](graphql/graphql-spec#635)

I've been working on the [implementation](graphql/graphql-js#2276) of the `@specified(by: "")` directive as specified by graphql/graphql-spec#649, and am interested an any feedback or progress on that effort.

IvanGoncharov · 2020-01-08T11:52:52Z

Reviewing graphql/graphql-js#2276 I saw another argument for naming argument url instead of by, since by by itself looks weird in code:
https://github.com/graphql/graphql-js/pull/2276/files#diff-71ba52e9c625f826d2b0df2963c8633aR328

I've been working on the [implementation](graphql/graphql-js#2276) of the `@specified(by: "")` directive as specified by graphql/graphql-spec#649, and am interested an any feedback or progress on that effort.

Co-Authored-By: Lee Byron <lee@leebyron.com>

One last follow up to #649 RFC, this uses the new term definition syntax and ensures the term usage is consistent throughout the document. Also makes a minor editorial change in the introspection section to list the `description` field under `name` like the other sections

eapache mentioned this pull request Nov 20, 2019

[RFC] Custom Scalar Specification URIs #635

Open

sungam3r reviewed Nov 20, 2019

View reviewed changes

andimarek reviewed Nov 20, 2019

View reviewed changes

leebyron reviewed Dec 5, 2019

View reviewed changes

m14t mentioned this pull request Dec 6, 2019

Add @specifiedBy directive graphql/graphql-js#2276

Merged

tinnou mentioned this pull request Dec 6, 2019

[RFC] Add note recommending directive names to be namespaced #657

Merged

m14t reviewed Dec 7, 2019

View reviewed changes

eapache changed the title ~~[RFC] Custom Scalar Specification URIs~~ [RFC] Custom Scalar Specification URLs Dec 10, 2019

eapache force-pushed the custom-scalar-formats branch from d8ed061 to f72a146 Compare December 10, 2019 19:00

eapache commented Dec 10, 2019

View reviewed changes

IvanGoncharov reviewed Dec 11, 2019

View reviewed changes

michaelstaib mentioned this pull request Dec 17, 2019

Configuration of AnyType ChilliCream/graphql-platform#1303

Closed

m14t reviewed Dec 30, 2019

View reviewed changes

m14t reviewed Dec 31, 2019

View reviewed changes

spec/Section 3 -- Type System.md Outdated Show resolved Hide resolved

m14t mentioned this pull request Jan 2, 2020

Add Matt Farmer to 2020-02-06.md agenda graphql/graphql-wg#324

Closed

m14t mentioned this pull request Jan 9, 2020

Add Matt Farmer to 2020-01-09 agenda graphql/graphql-wg#341

Merged

leebyron added the 📄 Draft (RFC 2) RFC Stage 2 (See CONTRIBUTING.md) label Jan 10, 2020

leebyron force-pushed the custom-scalar-formats branch from 1758a1c to cb92ed5 Compare January 11, 2020 01:37

eapache and others added 11 commits April 8, 2021 22:51

Update spec/Section 4 -- Introspection.md

42360e4

Co-Authored-By: Lee Byron <lee@leebyron.com>

Minor wording and formatting tweaks

4b5a285

Editorial

968f961

Editorial for Scalars section

6c58094

Editorial to reduce duplication and centralize info

bab4fab

Editorial - grammar

038b6f8

Editorial - simplify introspection change

eb18c03

Editorial - introspection description

96fb0d1

Editorial - return note about use of descriptions

f8065c3

Editorial - directive description

a2401b7

Update Section 3 -- Type System.md

318b753

leebyron force-pushed the custom-scalar-formats branch from c2e404e to 318b753 Compare April 9, 2021 06:01

leebyron added 2 commits April 8, 2021 23:04

address review

f2bf007

additional editorial adjustment

89014b9

leebyron merged commit d4a865a into graphql:main Apr 9, 2021

This was referenced Apr 9, 2021

@specifiedBy support graphql-dotnet/parser#128

Closed

@specifiedBy support graphql-dotnet/graphql-dotnet#2495

Open

This was referenced Apr 10, 2021

Add "specifiedBy" vektah/gqlparser#152

Closed

added specifiedBy gqlgo/gqlparser#7

Merged

Use specifiedBy instead of specifiedByUrl graphql/graphql-js#3032

Merged

Shane32 mentioned this pull request Apr 11, 2021

Expose user-defined meta-information via introspection API in form of directives #300

Open

Code-Hex mentioned this pull request Apr 12, 2021

fixed introspection field "specifiedBy" to "specifiedByURL" #848

Merged

leebyron mentioned this pull request Apr 16, 2021

Editorial: Define 'Schema Specification URL' #856

Merged

benjie mentioned this pull request May 14, 2021

[2020-07-02] Read over GraphQL Custom Scalar PR graphql/graphql-wg#509

Closed

This was referenced Dec 8, 2021

[GraphQL October 2021] Tracking issue graphql-rust/juniper#1000

Closed

[GraphQL October 2021] Support @specifiedBy(url: "...") directive (#1000) graphql-rust/juniper#1003

Merged

bhavinshah7 mentioned this pull request Mar 2, 2022

feat(dos-1294): add support for specifiedBy directive - (DOS-1294) graph-quilt/graphql-xtext#16

Merged

acao mentioned this pull request May 4, 2022

Support custom Scalar URLS graphql/graphiql#2386

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[RFC] Custom Scalar Specification URLs #649

[RFC] Custom Scalar Specification URLs #649

eapache commented Nov 20, 2019

sungam3r commented Nov 20, 2019

sungam3r Nov 20, 2019

michaelstaib Nov 20, 2019

sungam3r Nov 21, 2019

michaelstaib Nov 21, 2019

andimarek Nov 20, 2019

andimarek Nov 20, 2019

michaelstaib Nov 21, 2019

eapache Nov 26, 2019

eapache Nov 26, 2019

andimarek Nov 20, 2019

andimarek commented Nov 20, 2019

leebyron Dec 5, 2019

m14t Dec 7, 2019

eapache Dec 10, 2019 •

edited

Loading

eapache Dec 10, 2019

leebyron Jan 11, 2020

IvanGoncharov Dec 11, 2019

eapache Dec 16, 2019

IvanGoncharov commented Dec 15, 2019 •

edited

Loading

sungam3r commented Dec 15, 2019

eapache commented Dec 16, 2019

m14t Dec 30, 2019

eapache Feb 5, 2020

IvanGoncharov commented Jan 8, 2020

	# should be non-null for SCALAR only, must be null for the others
	# should be a string or null for SCALAR only, must be null for the others

[RFC] Custom Scalar Specification URLs #649

[RFC] Custom Scalar Specification URLs #649

Conversation

eapache commented Nov 20, 2019

sungam3r commented Nov 20, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andimarek commented Nov 20, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eapache Dec 10, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

IvanGoncharov commented Dec 15, 2019 • edited Loading

sungam3r commented Dec 15, 2019

eapache commented Dec 16, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

IvanGoncharov commented Jan 8, 2020

eapache Dec 10, 2019 •

edited

Loading

IvanGoncharov commented Dec 15, 2019 •

edited

Loading