Add Appendix D - Specified Type System Definitions by martinbonnin · Pull Request #1037 · graphql/graphql-spec

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	`3cf473a`
🔍 Latest deploy log	https://app.netlify.com/projects/graphql-spec-draft/deploys/685d8f6255c4820008a95131
😎 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

Changed the order to match graphql-js semantic ordering instead e274c76

See graphql/graphql-js#4428 (comment) for data about why semantic ordering is probably the safe bet.

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.

scripts/update-appendix-c.mjs

Co-authored-by: Benjie <benjie@jemjie.com>

See graphql/graphql-spec#1037 (comment)

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

leebyron · 2025-06-26T18:18:06Z

scripts/update-appendix-c.mjs

+const suffix = `
+\`\`\`
+`
+await writeFile(FILE, prefix + printSpecifiedScalars() + '\n\n' + introspectionSchema + suffix);


add a line break at the end

line break

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 <benjie@jemjie.com>

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

Closed

martinbonnin commented Jun 5, 2025

View reviewed changes

spec/Appendix C -- Built-in Definitions.md Outdated Show resolved Hide resolved

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 PascalSenn, Urigo, leebyron and michaelstaib June 6, 2025 12:02

update the order of fields to match graphql-js

e274c76

martinbonnin added the ✏️ Editorial PR is non-normative or does not influence implementation label Jun 24, 2025

leebyron reviewed Jun 26, 2025

View reviewed changes

Update update-appendix-c.mjs

3cf473a

line break

leebyron merged commit 9d0710e into graphql:main Jun 26, 2025
9 checks passed

tyranron mentioned this pull request Sep 8, 2025

GraphQL spec September 2025 graphql-rust/juniper#1347

Open

23 tasks

martinbonnin changed the title ~~Add Appendix C - Specified Type System Definitions~~ Add Appendix D - Specified Type System Definitions Sep 15, 2025

martinbonnin mentioned this pull request Sep 15, 2025

Fix includeDeprecated arg type in "Appendix D" #1192

Merged

Comments

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!

martinbonnin Jun 24, 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!

Uh oh!

Uh oh!

leebyron Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

martinbonnin commented Aug 5, 2023 •

edited

Loading

netlify bot commented Aug 5, 2023 •

edited

Loading

martinbonnin commented Mar 6, 2025 •

edited

Loading