Add Appendix C - Specified Type System Definitions #1037

martinbonnin · 2023-08-05T13:22:28Z

As we dive into full schemas, introspection and more (see #1036), I'd find it useful to have an authoritative source for built-in definitions that come with a GraphQL implementation (scalar, directives & introspection types).

It shows the type system definitions at a glance and makes it easy to diff, capture a change by looking at the git history. It's also nice for library authors because it uniformizes the descriptions.

The definitions are taken from graphql-js printIntrospectionSchema() with two small changes:

I added the scalars definitions manually
I carried over the __Type.fields, __Type.interface, etc... descriptions from the current spec comments

I was doing this for my own needs so figured out I might as well contribute it to the spec but I'm happy to move it somewhere else if you think this doesn't belong in the spec.

netlify · 2023-08-05T13:22:36Z

✅ Deploy Preview for graphql-spec-draft ready!

Name	Link
🔨 Latest commit	`d05591b`
🔍 Latest deploy log	https://app.netlify.com/projects/graphql-spec-draft/deploys/6841dd5b8a4b3300087d86e2
😎 Deploy Preview	https://deploy-preview-1037--graphql-spec-draft.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

martinbonnin · 2023-09-07T15:56:36Z

Would that qualify as an editorial change?

The validation/execution behaviour is essentially unchanged. The main thing that could be considered a behaviour change is that the definitions proposed here contain descriptions. We could either:

Remove descriptions
Add language that mandates the implementations use the same description as in the spec
Add language that the implementations are free to change the description if they want
Leave as is

benjie

Let's keep this to just adding the appendix, it does not need to be referenced in the spec text (just as Appendix B is not referenced when grammar is mentioned).

spec/Section 4 -- Introspection.md

spec/Section 3 -- Type System.md

Suggested changes were adopted.

martinbonnin · 2025-03-06T10:57:37Z

I guess there's a distinction to be made between:

implementations MUST always support it and expose the definition in introspection: @include, @defer, etc...
implementations MAY support it but it may not always be present in introspection: @defer, @disableErrorPropagation, etc...

~~So I'm questioning wether built-in definitions is the proper term there. Maybe just specified definitions? Or just definitions? Thoughts?~~

Edit: I settled on "Type System Definitions"

BoD

Added a few dots and capital letters.

spec/Appendix C -- Built-in Definitions.md

benjie

I reproduced your work by starting from a clean slate and then extracting the relevant definitions from the relevant sections; doing so revealed a few discrepancies that have crept in since you authored this:

benjie · 2025-04-03T09:02:11Z

spec/Appendix C -- Built-in Definitions.md

+  isRepeatable: Boolean!
+  locations: [__DirectiveLocation!]!
+  args(includeDeprecated: Boolean = false): [__InputValue!]!


Let's maintain the order of fields in the Introspection chapter

Suggested change

isRepeatable: Boolean!

locations: [__DirectiveLocation!]!

args(includeDeprecated: Boolean = false): [__InputValue!]!

locations: [__DirectiveLocation!]!

args(includeDeprecated: Boolean = false): [__InputValue!]!

isRepeatable: Boolean!

Either we should re-order this in the spec, or in GraphQL-js. We should make it consistent.

graphql/graphql-js#4428

spec/Appendix C -- Built-in Definitions.md

benjie

Let's discuss whether or not we need this, or whether it should be re-incorporated back into the other chapters of the spec... But if agreed that a new appendix is warranted then I confirm the current state of it as accurate 👍

Feedback addressed

martinbonnin · 2025-05-01T18:14:07Z

Feedback from May wg:

Put everything in one giant block
Add a script to get the block from graphql-js (update graphql-js if some things are out of order)

benjie

LGTM; couple minor suggestions.

scripts/update-appendix-c.mjs

benjie · 2025-06-05T14:57:43Z

spec/Appendix C -- Built-in Definitions.md

+  isRepeatable: Boolean!
+  locations: [__DirectiveLocation!]!
+  args(includeDeprecated: Boolean = false): [__InputValue!]!


Either we should re-order this in the spec, or in GraphQL-js. We should make it consistent.

benjie · 2025-06-05T15:01:30Z

scripts/update-appendix-c.mjs

+This appendix lists all the type system definitions mentioned throughout this
+specification.


Not exactly true as there are plenty of examples written as type system definitions which we have not included. Perhaps:

Suggested change

This appendix lists all the type system definitions mentioned throughout this

specification.

This appendix lists the introspection types and builtin directives mentioned

throughout this specification.

Also... We're missing the builtin scalars? Might need to add those manually, or add a flag to printIntrospectionSchema to include them.

We're missing the builtin scalars?

Yikes, your're right. I think we want those in graphql-js. I'll look into it.

there are plenty of examples written as type system definitions which we have not included.

Right. What about just:

Suggested change

This appendix lists all the type system definitions mentioned throughout this

specification.

This appendix lists the built-in type system definitions.

?

Actually, graphql-js has "specified scalars", which I think is exactly what we are looking for. I went with "specified type system definitions" in 275bf54, let me know how that looks.

Co-authored-by: Benjie <[email protected]>

See graphql/graphql-spec#1037 (comment)

martinbonnin · 2025-06-05T16:40:16Z

spec/Appendix C -- Built-in Definitions.md

+  enumValues(includeDeprecated: Boolean = false): [__EnumValue!]
+  inputFields(includeDeprecated: Boolean = false): [__InputValue!]
+  ofType: __Type
+  isOneOf: Boolean


Fun fact: I haven't found a version of GraphQL JS that matches the current draft:

16.11.0 has @oneOf but draft doesn't

16.8.0 doesn't have @oneOf but also doesn't have non-null includeDeprecated (which is in the draft)

martinbonnin mentioned this pull request Aug 7, 2023

Add mergeExtensions and toFullSchemaGQLDocument apollographql/apollo-kotlin#5162

Merged

martinbonnin mentioned this pull request Sep 7, 2023

[2023-08] full schemas: write a RFC that captures the WG discussion and a possible way forward graphql/graphql-wg#1367

Closed

benjie previously requested changes Sep 8, 2023

View reviewed changes

spec/Section 4 -- Introspection.md Outdated Show resolved Hide resolved

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

martinbonnin requested a review from benjie October 4, 2023 13:34

BoD reviewed Apr 3, 2025

View reviewed changes

BoD approved these changes Apr 3, 2025

View reviewed changes

benjie previously requested changes Apr 3, 2025

View reviewed changes

martinbonnin changed the title ~~Add Appendix C - Built-in Definitions~~ Add Appendix C - Type System Definitions Apr 3, 2025

benjie reviewed Apr 3, 2025

View reviewed changes

martinbonnin force-pushed the builtin-sdl branch from c064810 to e346598 Compare May 28, 2025 15:50

Add appendix C - builtin definitions

02670fc

martinbonnin force-pushed the builtin-sdl branch from e346598 to 02670fc Compare May 28, 2025 15:55

martinbonnin added 2 commits May 28, 2025 17:57

also run prettier

d397d1a

update graphql-js

ee90eb8

benjie approved these changes Jun 5, 2025

View reviewed changes

martinbonnin and others added 2 commits June 5, 2025 17:07

Update scripts/update-appendix-c.mjs

36bb5d6

Co-authored-by: Benjie <[email protected]>

add specified scalars

275bf54

martinbonnin force-pushed the builtin-sdl branch from fa541c3 to 275bf54 Compare June 5, 2025 15:54

martinbonnin changed the title ~~Add Appendix C - Type System Definitions~~ Add Appendix C - Specified Type System Definitions Jun 5, 2025

martinbonnin added a commit to martinbonnin/graphql-js that referenced this pull request Jun 5, 2025

Keep order of definitions consistent with the spec

f86b602

See graphql/graphql-spec#1037 (comment)

martinbonnin added a commit to martinbonnin/graphql-js that referenced this pull request Jun 5, 2025

Keep order of definitions consistent with the spec

0f180a3

See graphql/graphql-spec#1037 (comment)

martinbonnin mentioned this pull request Jun 5, 2025

Keep order of specified definitions consistent with the spec graphql/graphql-js#4428

Open

martinbonnin commented Jun 5, 2025

View reviewed changes

manual tweaking

370cfaa

martinbonnin force-pushed the builtin-sdl branch from 6adfbee to 370cfaa Compare June 5, 2025 17:34

martinbonnin added 2 commits June 5, 2025 19:39

built-in => specified

dcc22ec

another instance of BuiltIn => Specified

d05591b

martinbonnin force-pushed the builtin-sdl branch from 0c17ee7 to d05591b Compare June 5, 2025 18:09

BoD approved these changes Jun 6, 2025

View reviewed changes

martinbonnin requested review from leebyron, Urigo, michaelstaib and PascalSenn June 6, 2025 12:02

		This appendix lists all the type system definitions mentioned throughout this
		specification.

	This appendix lists all the type system definitions mentioned throughout this
	specification.
	This appendix lists the built-in type system definitions.

Add Appendix C - Specified Type System Definitions #1037

Are you sure you want to change the base?

Add Appendix C - Specified Type System Definitions #1037

Uh oh!

Conversation

martinbonnin commented Aug 5, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Aug 5, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for graphql-spec-draft ready!

Uh oh!

martinbonnin commented Sep 7, 2023

Uh oh!

benjie left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

martinbonnin commented Mar 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BoD left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

benjie left a comment

Choose a reason for hiding this comment

Uh oh!

benjie Apr 3, 2025

Choose a reason for hiding this comment

Uh oh!

benjie Jun 5, 2025

Choose a reason for hiding this comment

Uh oh!

martinbonnin Jun 5, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

benjie left a comment

Choose a reason for hiding this comment

Uh oh!

martinbonnin commented May 1, 2025

Uh oh!

benjie left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

benjie Jun 5, 2025

Choose a reason for hiding this comment

Uh oh!

benjie Jun 5, 2025

Choose a reason for hiding this comment

Uh oh!

martinbonnin Jun 5, 2025

Choose a reason for hiding this comment

Uh oh!

martinbonnin Jun 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

martinbonnin Jun 5, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

martinbonnin commented Aug 5, 2023 •

edited

Loading

netlify bot commented Aug 5, 2023 •

edited

Loading

martinbonnin commented Mar 6, 2025 •

edited

Loading

martinbonnin Jun 5, 2025 •

edited

Loading