From 02670fcb25d652b85317947118dc6b54862408a3 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Wed, 28 May 2025 17:34:11 +0200 Subject: [PATCH 1/8] Add appendix C - builtin definitions --- package-lock.json | 17 ++ package.json | 6 +- scripts/update-appendix-c.mjs | 22 ++ spec/Appendix C -- Built-in Definitions.md | 236 +++++++++++++++++++++ spec/GraphQL.md | 2 + 5 files changed, 281 insertions(+), 2 deletions(-) create mode 100644 scripts/update-appendix-c.mjs create mode 100644 spec/Appendix C -- Built-in Definitions.md diff --git a/package-lock.json b/package-lock.json index 18251dd1d..c83c20b7a 100644 --- a/package-lock.json +++ b/package-lock.json @@ -8,6 +8,7 @@ "license": "OWFa-1.0", "devDependencies": { "cspell": "5.9.1", + "graphql": "^16.11.0", "nodemon": "2.0.20", "prettier": "2.8.2", "spec-md": "3.1.0" @@ -893,6 +894,16 @@ "integrity": "sha512-WjKPNJF79dtJAVniUlGGWHYGz2jWxT6VhN/4m1NdkbZ2nOsEF+cI1Edgql5zCRhs/VsQYRvrXctxktVXZUkixw==", "dev": true }, + "node_modules/graphql": { + "version": "16.11.0", + "resolved": "https://registry.npmjs.org/graphql/-/graphql-16.11.0.tgz", + "integrity": "sha512-mS1lbMsxgQj6hge1XZ6p7GPhbrtFwUFYi3wRzXAC/FmYnyXMTvvI3td3rjmQ2u8ewXueaSvRPWaEcgVVOT9Jnw==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^12.22.0 || ^14.16.0 || ^16.0.0 || >=17.0.0" + } + }, "node_modules/has-flag": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz", @@ -2304,6 +2315,12 @@ "integrity": "sha512-WjKPNJF79dtJAVniUlGGWHYGz2jWxT6VhN/4m1NdkbZ2nOsEF+cI1Edgql5zCRhs/VsQYRvrXctxktVXZUkixw==", "dev": true }, + "graphql": { + "version": "16.11.0", + "resolved": "https://registry.npmjs.org/graphql/-/graphql-16.11.0.tgz", + "integrity": "sha512-mS1lbMsxgQj6hge1XZ6p7GPhbrtFwUFYi3wRzXAC/FmYnyXMTvvI3td3rjmQ2u8ewXueaSvRPWaEcgVVOT9Jnw==", + "dev": true + }, "has-flag": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz", diff --git a/package.json b/package.json index 0d05daa05..e91a7396d 100644 --- a/package.json +++ b/package.json @@ -21,13 +21,15 @@ "suggest:format": "echo \"\nTo resolve this, run: $(tput bold)npm run format$(tput sgr0)\" && exit 1", "build": "./build.sh", "test:build": "spec-md --metadata spec/metadata.json spec/GraphQL.md > /dev/null", - "watch": "nodemon -e json,md --exec \"npm run build\"" + "watch": "nodemon -e json,md --exec \"npm run build\"", + "update-appendix-c": "node scripts/update-appendix-c.mjs" }, "devDependencies": { "cspell": "5.9.1", "nodemon": "2.0.20", "prettier": "2.8.2", - "spec-md": "3.1.0" + "spec-md": "3.1.0", + "graphql": "^16.11.0" }, "prettier": { "proseWrap": "always", diff --git a/scripts/update-appendix-c.mjs b/scripts/update-appendix-c.mjs new file mode 100644 index 000000000..7c3e413d0 --- /dev/null +++ b/scripts/update-appendix-c.mjs @@ -0,0 +1,22 @@ +import { writeFile } from 'node:fs/promises'; +import { printIntrospectionSchema, buildSchema } from 'graphql'; + +const FILE = './spec/Appendix C -- Built-in Definitions.md'; + +const sdl = printIntrospectionSchema(buildSchema(`type Query { i: Int }`)); +const prefix = ` +# C. Appendix: Type System Definitions + +This appendix lists all the type system definitions mentioned throughout this +specification. + +The descriptions are non-normative. Implementations are recommended to use them +for consistency but different descriptions are allowed. + +\`\`\`graphql +` + +const suffix = ` +\`\`\` +` +await writeFile(FILE, prefix + sdl + suffix); \ No newline at end of file diff --git a/spec/Appendix C -- Built-in Definitions.md b/spec/Appendix C -- Built-in Definitions.md new file mode 100644 index 000000000..b92c87ffb --- /dev/null +++ b/spec/Appendix C -- Built-in Definitions.md @@ -0,0 +1,236 @@ + +# C. Appendix: Type System Definitions + +This appendix lists all the type system definitions mentioned throughout this +specification. + +The descriptions are non-normative. Implementations are recommended to use them +for consistency but different descriptions are allowed. + +```graphql +""" +Directs the executor to include this field or fragment only when the `if` argument is true. +""" +directive @include( + """Included when true.""" + if: Boolean! +) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT + +""" +Directs the executor to skip this field or fragment when the `if` argument is true. +""" +directive @skip( + """Skipped when true.""" + if: Boolean! +) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT + +"""Marks an element of a GraphQL schema as no longer supported.""" +directive @deprecated( + """ + Explains why this element was deprecated, usually also including a suggestion for how to access supported similar data. Formatted using the Markdown syntax, as specified by [CommonMark](https://commonmark.org/). + """ + reason: String = "No longer supported" +) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE + +"""Exposes a URL that specifies the behavior of this scalar.""" +directive @specifiedBy( + """The URL that specifies the behavior of this scalar.""" + url: String! +) on SCALAR + +""" +Indicates exactly one field must be supplied and this field must not be `null`. +""" +directive @oneOf on INPUT_OBJECT + +""" +A GraphQL Schema defines the capabilities of a GraphQL server. It exposes all available types and directives on the server, as well as the entry points for query, mutation, and subscription operations. +""" +type __Schema { + description: String + + """A list of all types supported by this server.""" + types: [__Type!]! + + """The type that query operations will be rooted at.""" + queryType: __Type! + + """ + If this server supports mutation, the type that mutation operations will be rooted at. + """ + mutationType: __Type + + """ + If this server support subscription, the type that subscription operations will be rooted at. + """ + subscriptionType: __Type + + """A list of all directives supported by this server.""" + directives: [__Directive!]! +} + +""" +The fundamental unit of any GraphQL Schema is the type. There are many kinds of types in GraphQL as represented by the `__TypeKind` enum. + +Depending on the kind of a type, certain fields describe information about that type. Scalar types provide no information beyond a name, description and optional `specifiedByURL`, while Enum types provide their values. Object and Interface types provide the fields they describe. Abstract types, Union and Interface, provide the Object types possible at runtime. List and NonNull types compose other types. +""" +type __Type { + kind: __TypeKind! + name: String + description: String + specifiedByURL: String + fields(includeDeprecated: Boolean = false): [__Field!] + interfaces: [__Type!] + possibleTypes: [__Type!] + enumValues(includeDeprecated: Boolean = false): [__EnumValue!] + inputFields(includeDeprecated: Boolean = false): [__InputValue!] + ofType: __Type + isOneOf: Boolean +} + +"""An enum describing what kind of type a given `__Type` is.""" +enum __TypeKind { + """Indicates this type is a scalar.""" + SCALAR + + """ + Indicates this type is an object. `fields` and `interfaces` are valid fields. + """ + OBJECT + + """ + Indicates this type is an interface. `fields`, `interfaces`, and `possibleTypes` are valid fields. + """ + INTERFACE + + """Indicates this type is a union. `possibleTypes` is a valid field.""" + UNION + + """Indicates this type is an enum. `enumValues` is a valid field.""" + ENUM + + """ + Indicates this type is an input object. `inputFields` is a valid field. + """ + INPUT_OBJECT + + """Indicates this type is a list. `ofType` is a valid field.""" + LIST + + """Indicates this type is a non-null. `ofType` is a valid field.""" + NON_NULL +} + +""" +Object and Interface types are described by a list of Fields, each of which has a name, potentially a list of arguments, and a return type. +""" +type __Field { + name: String! + description: String + args(includeDeprecated: Boolean = false): [__InputValue!]! + type: __Type! + isDeprecated: Boolean! + deprecationReason: String +} + +""" +Arguments provided to Fields or Directives and the input fields of an InputObject are represented as Input Values which describe their type and optionally a default value. +""" +type __InputValue { + name: String! + description: String + type: __Type! + + """ + A GraphQL-formatted string representing the default value for this input value. + """ + defaultValue: String + isDeprecated: Boolean! + deprecationReason: String +} + +""" +One possible value for a given Enum. Enum values are unique values, not a placeholder for a string or numeric value. However an Enum value is returned in a JSON response as a string. +""" +type __EnumValue { + name: String! + description: String + isDeprecated: Boolean! + deprecationReason: String +} + +""" +A Directive provides a way to describe alternate runtime execution and type validation behavior in a GraphQL document. + +In some cases, you need to provide options to alter GraphQL's execution behavior in ways field arguments will not suffice, such as conditionally including or skipping a field. Directives provide this by describing additional information to the executor. +""" +type __Directive { + name: String! + description: String + isRepeatable: Boolean! + locations: [__DirectiveLocation!]! + args(includeDeprecated: Boolean = false): [__InputValue!]! +} + +""" +A Directive can be adjacent to many parts of the GraphQL language, a __DirectiveLocation describes one such possible adjacencies. +""" +enum __DirectiveLocation { + """Location adjacent to a query operation.""" + QUERY + + """Location adjacent to a mutation operation.""" + MUTATION + + """Location adjacent to a subscription operation.""" + SUBSCRIPTION + + """Location adjacent to a field.""" + FIELD + + """Location adjacent to a fragment definition.""" + FRAGMENT_DEFINITION + + """Location adjacent to a fragment spread.""" + FRAGMENT_SPREAD + + """Location adjacent to an inline fragment.""" + INLINE_FRAGMENT + + """Location adjacent to a variable definition.""" + VARIABLE_DEFINITION + + """Location adjacent to a schema definition.""" + SCHEMA + + """Location adjacent to a scalar definition.""" + SCALAR + + """Location adjacent to an object type definition.""" + OBJECT + + """Location adjacent to a field definition.""" + FIELD_DEFINITION + + """Location adjacent to an argument definition.""" + ARGUMENT_DEFINITION + + """Location adjacent to an interface definition.""" + INTERFACE + + """Location adjacent to a union definition.""" + UNION + + """Location adjacent to an enum definition.""" + ENUM + + """Location adjacent to an enum value definition.""" + ENUM_VALUE + + """Location adjacent to an input object type definition.""" + INPUT_OBJECT + + """Location adjacent to an input object field definition.""" + INPUT_FIELD_DEFINITION +} +``` diff --git a/spec/GraphQL.md b/spec/GraphQL.md index fad6bcdbe..362227aec 100644 --- a/spec/GraphQL.md +++ b/spec/GraphQL.md @@ -139,3 +139,5 @@ Note: This is an example of a non-normative note. # [Appendix: Notation Conventions](Appendix%20A%20--%20Notation%20Conventions.md) # [Appendix: Grammar Summary](Appendix%20B%20--%20Grammar%20Summary.md) + +# [Appendix: Builtin Definitions](Appendix%20C%20--%20Built-in%20Definitions.md) From d397d1a0ca689c94e9b5c8b56c0793c30d2b857c Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Wed, 28 May 2025 17:57:32 +0200 Subject: [PATCH 2/8] also run prettier --- package.json | 2 +- spec/Appendix C -- Built-in Definitions.md | 133 +++++++++++++++------ 2 files changed, 100 insertions(+), 35 deletions(-) diff --git a/package.json b/package.json index e91a7396d..7084e4da5 100644 --- a/package.json +++ b/package.json @@ -22,7 +22,7 @@ "build": "./build.sh", "test:build": "spec-md --metadata spec/metadata.json spec/GraphQL.md > /dev/null", "watch": "nodemon -e json,md --exec \"npm run build\"", - "update-appendix-c": "node scripts/update-appendix-c.mjs" + "update-appendix-c": "node scripts/update-appendix-c.mjs; prettier --write \"spec/Appendix C -- Built-in Definitions.md\"" }, "devDependencies": { "cspell": "5.9.1", diff --git a/spec/Appendix C -- Built-in Definitions.md b/spec/Appendix C -- Built-in Definitions.md index b92c87ffb..4c4419c89 100644 --- a/spec/Appendix C -- Built-in Definitions.md +++ b/spec/Appendix C -- Built-in Definitions.md @@ -1,4 +1,3 @@ - # C. Appendix: Type System Definitions This appendix lists all the type system definitions mentioned throughout this @@ -12,7 +11,9 @@ for consistency but different descriptions are allowed. Directs the executor to include this field or fragment only when the `if` argument is true. """ directive @include( - """Included when true.""" + """ + Included when true. + """ if: Boolean! ) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT @@ -20,11 +21,15 @@ directive @include( Directs the executor to skip this field or fragment when the `if` argument is true. """ directive @skip( - """Skipped when true.""" + """ + Skipped when true. + """ if: Boolean! ) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT -"""Marks an element of a GraphQL schema as no longer supported.""" +""" +Marks an element of a GraphQL schema as no longer supported. +""" directive @deprecated( """ Explains why this element was deprecated, usually also including a suggestion for how to access supported similar data. Formatted using the Markdown syntax, as specified by [CommonMark](https://commonmark.org/). @@ -32,9 +37,13 @@ directive @deprecated( reason: String = "No longer supported" ) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE -"""Exposes a URL that specifies the behavior of this scalar.""" +""" +Exposes a URL that specifies the behavior of this scalar. +""" directive @specifiedBy( - """The URL that specifies the behavior of this scalar.""" + """ + The URL that specifies the behavior of this scalar. + """ url: String! ) on SCALAR @@ -49,10 +58,14 @@ A GraphQL Schema defines the capabilities of a GraphQL server. It exposes all av type __Schema { description: String - """A list of all types supported by this server.""" + """ + A list of all types supported by this server. + """ types: [__Type!]! - """The type that query operations will be rooted at.""" + """ + The type that query operations will be rooted at. + """ queryType: __Type! """ @@ -65,7 +78,9 @@ type __Schema { """ subscriptionType: __Type - """A list of all directives supported by this server.""" + """ + A list of all directives supported by this server. + """ directives: [__Directive!]! } @@ -88,9 +103,13 @@ type __Type { isOneOf: Boolean } -"""An enum describing what kind of type a given `__Type` is.""" +""" +An enum describing what kind of type a given `__Type` is. +""" enum __TypeKind { - """Indicates this type is a scalar.""" + """ + Indicates this type is a scalar. + """ SCALAR """ @@ -103,10 +122,14 @@ enum __TypeKind { """ INTERFACE - """Indicates this type is a union. `possibleTypes` is a valid field.""" + """ + Indicates this type is a union. `possibleTypes` is a valid field. + """ UNION - """Indicates this type is an enum. `enumValues` is a valid field.""" + """ + Indicates this type is an enum. `enumValues` is a valid field. + """ ENUM """ @@ -114,10 +137,14 @@ enum __TypeKind { """ INPUT_OBJECT - """Indicates this type is a list. `ofType` is a valid field.""" + """ + Indicates this type is a list. `ofType` is a valid field. + """ LIST - """Indicates this type is a non-null. `ofType` is a valid field.""" + """ + Indicates this type is a non-null. `ofType` is a valid field. + """ NON_NULL } @@ -176,61 +203,99 @@ type __Directive { A Directive can be adjacent to many parts of the GraphQL language, a __DirectiveLocation describes one such possible adjacencies. """ enum __DirectiveLocation { - """Location adjacent to a query operation.""" + """ + Location adjacent to a query operation. + """ QUERY - """Location adjacent to a mutation operation.""" + """ + Location adjacent to a mutation operation. + """ MUTATION - """Location adjacent to a subscription operation.""" + """ + Location adjacent to a subscription operation. + """ SUBSCRIPTION - """Location adjacent to a field.""" + """ + Location adjacent to a field. + """ FIELD - """Location adjacent to a fragment definition.""" + """ + Location adjacent to a fragment definition. + """ FRAGMENT_DEFINITION - """Location adjacent to a fragment spread.""" + """ + Location adjacent to a fragment spread. + """ FRAGMENT_SPREAD - """Location adjacent to an inline fragment.""" + """ + Location adjacent to an inline fragment. + """ INLINE_FRAGMENT - """Location adjacent to a variable definition.""" + """ + Location adjacent to a variable definition. + """ VARIABLE_DEFINITION - """Location adjacent to a schema definition.""" + """ + Location adjacent to a schema definition. + """ SCHEMA - """Location adjacent to a scalar definition.""" + """ + Location adjacent to a scalar definition. + """ SCALAR - """Location adjacent to an object type definition.""" + """ + Location adjacent to an object type definition. + """ OBJECT - """Location adjacent to a field definition.""" + """ + Location adjacent to a field definition. + """ FIELD_DEFINITION - """Location adjacent to an argument definition.""" + """ + Location adjacent to an argument definition. + """ ARGUMENT_DEFINITION - """Location adjacent to an interface definition.""" + """ + Location adjacent to an interface definition. + """ INTERFACE - """Location adjacent to a union definition.""" + """ + Location adjacent to a union definition. + """ UNION - """Location adjacent to an enum definition.""" + """ + Location adjacent to an enum definition. + """ ENUM - """Location adjacent to an enum value definition.""" + """ + Location adjacent to an enum value definition. + """ ENUM_VALUE - """Location adjacent to an input object type definition.""" + """ + Location adjacent to an input object type definition. + """ INPUT_OBJECT - """Location adjacent to an input object field definition.""" + """ + Location adjacent to an input object field definition. + """ INPUT_FIELD_DEFINITION } ``` From ee90eb8ec156e26cf53557598e8185209a9e00e7 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Wed, 28 May 2025 18:01:19 +0200 Subject: [PATCH 3/8] update graphql-js --- package-lock.json | 16 ++++++++-------- package.json | 2 +- spec/Appendix C -- Built-in Definitions.md | 9 +++++++-- 3 files changed, 16 insertions(+), 11 deletions(-) diff --git a/package-lock.json b/package-lock.json index c83c20b7a..0a015fcca 100644 --- a/package-lock.json +++ b/package-lock.json @@ -8,7 +8,7 @@ "license": "OWFa-1.0", "devDependencies": { "cspell": "5.9.1", - "graphql": "^16.11.0", + "graphql": "^17.0.0-alpha.8", "nodemon": "2.0.20", "prettier": "2.8.2", "spec-md": "3.1.0" @@ -895,13 +895,13 @@ "dev": true }, "node_modules/graphql": { - "version": "16.11.0", - "resolved": "https://registry.npmjs.org/graphql/-/graphql-16.11.0.tgz", - "integrity": "sha512-mS1lbMsxgQj6hge1XZ6p7GPhbrtFwUFYi3wRzXAC/FmYnyXMTvvI3td3rjmQ2u8ewXueaSvRPWaEcgVVOT9Jnw==", + "version": "17.0.0-alpha.8", + "resolved": "https://registry.npmjs.org/graphql/-/graphql-17.0.0-alpha.8.tgz", + "integrity": "sha512-j9Jn56NCWVaLMt1hSNkMDoCuAisBwY3bxp/5tbrJuPtNtHg9dAf4NjKnlVDCksVP3jBVcipFaEXKWsdNxTlcyg==", "dev": true, "license": "MIT", "engines": { - "node": "^12.22.0 || ^14.16.0 || ^16.0.0 || >=17.0.0" + "node": "^16.19.0 || ^18.14.0 || >=19.7.0" } }, "node_modules/has-flag": { @@ -2316,9 +2316,9 @@ "dev": true }, "graphql": { - "version": "16.11.0", - "resolved": "https://registry.npmjs.org/graphql/-/graphql-16.11.0.tgz", - "integrity": "sha512-mS1lbMsxgQj6hge1XZ6p7GPhbrtFwUFYi3wRzXAC/FmYnyXMTvvI3td3rjmQ2u8ewXueaSvRPWaEcgVVOT9Jnw==", + "version": "17.0.0-alpha.8", + "resolved": "https://registry.npmjs.org/graphql/-/graphql-17.0.0-alpha.8.tgz", + "integrity": "sha512-j9Jn56NCWVaLMt1hSNkMDoCuAisBwY3bxp/5tbrJuPtNtHg9dAf4NjKnlVDCksVP3jBVcipFaEXKWsdNxTlcyg==", "dev": true }, "has-flag": { diff --git a/package.json b/package.json index 7084e4da5..afca0f11e 100644 --- a/package.json +++ b/package.json @@ -29,7 +29,7 @@ "nodemon": "2.0.20", "prettier": "2.8.2", "spec-md": "3.1.0", - "graphql": "^16.11.0" + "graphql": "^17.0.0-alpha.8" }, "prettier": { "proseWrap": "always", diff --git a/spec/Appendix C -- Built-in Definitions.md b/spec/Appendix C -- Built-in Definitions.md index 4c4419c89..18d5622c6 100644 --- a/spec/Appendix C -- Built-in Definitions.md +++ b/spec/Appendix C -- Built-in Definitions.md @@ -34,7 +34,7 @@ directive @deprecated( """ Explains why this element was deprecated, usually also including a suggestion for how to access supported similar data. Formatted using the Markdown syntax, as specified by [CommonMark](https://commonmark.org/). """ - reason: String = "No longer supported" + reason: String! = "No longer supported" ) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE """ @@ -239,10 +239,15 @@ enum __DirectiveLocation { INLINE_FRAGMENT """ - Location adjacent to a variable definition. + Location adjacent to an operation variable definition. """ VARIABLE_DEFINITION + """ + Location adjacent to a fragment variable definition. + """ + FRAGMENT_VARIABLE_DEFINITION + """ Location adjacent to a schema definition. """ From 36bb5d6a3f8c2c64393b9ea66e020cb66ee4fbb2 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Thu, 5 Jun 2025 17:07:36 +0200 Subject: [PATCH 4/8] Update scripts/update-appendix-c.mjs Co-authored-by: Benjie --- scripts/update-appendix-c.mjs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/scripts/update-appendix-c.mjs b/scripts/update-appendix-c.mjs index 7c3e413d0..ac20ffbc0 100644 --- a/scripts/update-appendix-c.mjs +++ b/scripts/update-appendix-c.mjs @@ -13,6 +13,8 @@ specification. The descriptions are non-normative. Implementations are recommended to use them for consistency but different descriptions are allowed. +The order of types, fields, arguments, values and directives is non-normative. + \`\`\`graphql ` From 275bf5476ab1f26e4f92a53f83d541c7bb252354 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Thu, 5 Jun 2025 17:50:23 +0200 Subject: [PATCH 5/8] add specified scalars --- scripts/update-appendix-c.mjs | 14 ++++++---- spec/Appendix C -- Built-in Definitions.md | 30 ++++++++++++++++++++-- 2 files changed, 37 insertions(+), 7 deletions(-) diff --git a/scripts/update-appendix-c.mjs b/scripts/update-appendix-c.mjs index ac20ffbc0..25afec1c9 100644 --- a/scripts/update-appendix-c.mjs +++ b/scripts/update-appendix-c.mjs @@ -1,14 +1,18 @@ import { writeFile } from 'node:fs/promises'; -import { printIntrospectionSchema, buildSchema } from 'graphql'; +import { printIntrospectionSchema, buildSchema, specifiedScalarTypes, printType } from 'graphql'; const FILE = './spec/Appendix C -- Built-in Definitions.md'; +function printSpecifiedScalars() { + return specifiedScalarTypes + .map((type) => printType(type)) + .join('\n\n'); +} -const sdl = printIntrospectionSchema(buildSchema(`type Query { i: Int }`)); +const introspectionSchema = printIntrospectionSchema(buildSchema(`type Query { i: Int }`)); const prefix = ` # C. Appendix: Type System Definitions -This appendix lists all the type system definitions mentioned throughout this -specification. +This appendix lists the specified type system definitions. The descriptions are non-normative. Implementations are recommended to use them for consistency but different descriptions are allowed. @@ -21,4 +25,4 @@ The order of types, fields, arguments, values and directives is non-normative. const suffix = ` \`\`\` ` -await writeFile(FILE, prefix + sdl + suffix); \ No newline at end of file +await writeFile(FILE, prefix + printSpecifiedScalars() + '\n\n' + introspectionSchema + suffix); \ No newline at end of file diff --git a/spec/Appendix C -- Built-in Definitions.md b/spec/Appendix C -- Built-in Definitions.md index 18d5622c6..421970423 100644 --- a/spec/Appendix C -- Built-in Definitions.md +++ b/spec/Appendix C -- Built-in Definitions.md @@ -1,12 +1,38 @@ # C. Appendix: Type System Definitions -This appendix lists all the type system definitions mentioned throughout this -specification. +This appendix lists the specified type system definitions. The descriptions are non-normative. Implementations are recommended to use them for consistency but different descriptions are allowed. +The order of types, fields, arguments, values and directives is non-normative. + ```graphql +""" +The `String` scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text. +""" +scalar String + +""" +The `Int` scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1. +""" +scalar Int + +""" +The `Float` scalar type represents signed double-precision fractional values as specified by [IEEE 754](https://en.wikipedia.org/wiki/IEEE_floating_point). +""" +scalar Float + +""" +The `Boolean` scalar type represents `true` or `false`. +""" +scalar Boolean + +""" +The `ID` scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `"4"`) or integer (such as `4`) input value will be accepted as an ID. +""" +scalar ID + """ Directs the executor to include this field or fragment only when the `if` argument is true. """ From 370cfaa3c6be1602bd468664530c7b31460b7ad9 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Thu, 5 Jun 2025 18:40:41 +0200 Subject: [PATCH 6/8] manual tweaking --- spec/Appendix C -- Built-in Definitions.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/spec/Appendix C -- Built-in Definitions.md b/spec/Appendix C -- Built-in Definitions.md index 421970423..0cbbd0869 100644 --- a/spec/Appendix C -- Built-in Definitions.md +++ b/spec/Appendix C -- Built-in Definitions.md @@ -73,11 +73,6 @@ directive @specifiedBy( url: String! ) on SCALAR -""" -Indicates exactly one field must be supplied and this field must not be `null`. -""" -directive @oneOf on INPUT_OBJECT - """ A GraphQL Schema defines the capabilities of a GraphQL server. It exposes all available types and directives on the server, as well as the entry points for query, mutation, and subscription operations. """ @@ -126,7 +121,6 @@ type __Type { enumValues(includeDeprecated: Boolean = false): [__EnumValue!] inputFields(includeDeprecated: Boolean = false): [__InputValue!] ofType: __Type - isOneOf: Boolean } """ @@ -269,11 +263,6 @@ enum __DirectiveLocation { """ VARIABLE_DEFINITION - """ - Location adjacent to a fragment variable definition. - """ - FRAGMENT_VARIABLE_DEFINITION - """ Location adjacent to a schema definition. """ From dcc22ec38791083f0077f860d30a49dfcd8721aa Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Thu, 5 Jun 2025 19:39:39 +0200 Subject: [PATCH 7/8] built-in => specified --- scripts/update-appendix-c.mjs | 2 +- ...in Definitions.md => Appendix C -- Specified Definitions.md} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename spec/{Appendix C -- Built-in Definitions.md => Appendix C -- Specified Definitions.md} (100%) diff --git a/scripts/update-appendix-c.mjs b/scripts/update-appendix-c.mjs index 25afec1c9..0f7693c36 100644 --- a/scripts/update-appendix-c.mjs +++ b/scripts/update-appendix-c.mjs @@ -1,7 +1,7 @@ import { writeFile } from 'node:fs/promises'; import { printIntrospectionSchema, buildSchema, specifiedScalarTypes, printType } from 'graphql'; -const FILE = './spec/Appendix C -- Built-in Definitions.md'; +const FILE = './spec/Appendix C -- Specified Definitions.md'; function printSpecifiedScalars() { return specifiedScalarTypes .map((type) => printType(type)) diff --git a/spec/Appendix C -- Built-in Definitions.md b/spec/Appendix C -- Specified Definitions.md similarity index 100% rename from spec/Appendix C -- Built-in Definitions.md rename to spec/Appendix C -- Specified Definitions.md From d05591ba3cb29cb4c5cf75f025fe0a189339658f Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Thu, 5 Jun 2025 19:42:48 +0200 Subject: [PATCH 8/8] another instance of BuiltIn => Specified --- spec/GraphQL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/GraphQL.md b/spec/GraphQL.md index 362227aec..a1732e953 100644 --- a/spec/GraphQL.md +++ b/spec/GraphQL.md @@ -140,4 +140,4 @@ Note: This is an example of a non-normative note. # [Appendix: Grammar Summary](Appendix%20B%20--%20Grammar%20Summary.md) -# [Appendix: Builtin Definitions](Appendix%20C%20--%20Built-in%20Definitions.md) +# [Appendix: Specified Definitions](Appendix%20C%20--%20Specified%20Definitions.md)