Skip to content

Commit 3e4bdf8

Browse files
authored
Merge branch 'graphql:main' into schema_coordinates_spec_edit
2 parents c0dee02 + b1a23de commit 3e4bdf8

14 files changed

+1002
-325
lines changed

package-lock.json

Lines changed: 17 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

package.json

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,15 @@
2121
"suggest:format": "echo \"\nTo resolve this, run: $(tput bold)npm run format$(tput sgr0)\" && exit 1",
2222
"build": "./build.sh",
2323
"test:build": "spec-md --metadata spec/metadata.json spec/GraphQL.md > /dev/null",
24-
"watch": "nodemon -e json,md --exec \"npm run build\""
24+
"watch": "nodemon -e json,md --exec \"npm run build\"",
25+
"update-appendix-c": "node scripts/update-appendix-c.mjs; prettier --write \"spec/Appendix C -- Built-in Definitions.md\""
2526
},
2627
"devDependencies": {
2728
"cspell": "5.9.1",
2829
"nodemon": "2.0.20",
2930
"prettier": "2.8.2",
30-
"spec-md": "3.1.0"
31+
"spec-md": "3.1.0",
32+
"graphql": "^17.0.0-alpha.8"
3133
},
3234
"prettier": {
3335
"proseWrap": "always",

scripts/update-appendix-c.mjs

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
import { writeFile } from 'node:fs/promises';
2+
import { printIntrospectionSchema, buildSchema, specifiedScalarTypes, printType } from 'graphql';
3+
4+
const FILE = './spec/Appendix C -- Specified Definitions.md';
5+
function printSpecifiedScalars() {
6+
return specifiedScalarTypes
7+
.map((type) => printType(type))
8+
.join('\n\n');
9+
}
10+
11+
const introspectionSchema = printIntrospectionSchema(buildSchema(`type Query { i: Int }`));
12+
const prefix = `
13+
# C. Appendix: Type System Definitions
14+
15+
This appendix lists the specified type system definitions.
16+
17+
The descriptions are non-normative. Implementations are recommended to use them
18+
for consistency but different descriptions are allowed.
19+
20+
The order of types, fields, arguments, values and directives is non-normative.
21+
22+
\`\`\`graphql
23+
`
24+
25+
const suffix = `
26+
\`\`\`
27+
`
28+
await writeFile(FILE, prefix + printSpecifiedScalars() + '\n\n' + introspectionSchema + suffix);

spec/Appendix A -- Notation Conventions.md

Lines changed: 33 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -214,5 +214,36 @@ Fibonacci(number):
214214
- Return {Fibonacci(previousNumber)} + {Fibonacci(previousPreviousNumber)}.
215215

216216
Note: Algorithms described in this document are written to be easy to
217-
understand. Implementers are encouraged to include equivalent but optimized
218-
implementations.
217+
understand. Implementers are encouraged to include observably equivalent but
218+
optimized implementations.
219+
220+
## Data Collections
221+
222+
Algorithms within this specification refer to abstract data collection types to
223+
express normative structural, uniqueness, and ordering requirements. Temporary
224+
data collections internal to an algorithm use these types to best describe
225+
expected behavior, but implementers are encouraged to provide observably
226+
equivalent but optimized implementations. Implementations may use any data
227+
structure as long as the expected requirements are met.
228+
229+
**List**
230+
231+
:: A _list_ is an ordered collection of values which may contain duplicates. A
232+
value added to a list is ordered after existing values.
233+
234+
**Set**
235+
236+
:: A _set_ is a collection of values which must not contain duplicates.
237+
238+
:: An _ordered set_ is a set which has a defined order. A value added to an
239+
ordered set, which does not already contain that value, is ordered after
240+
existing values.
241+
242+
**Map**
243+
244+
:: A _map_ is a collection of entries, each of which has a key and value. Each
245+
entry has a unique key, and can be directly referenced by that key.
246+
247+
:: An _ordered map_ is a map which has a defined order. An entry added to an
248+
ordered map, which does not have an entry with that key, is ordered after
249+
existing entries.

spec/Appendix B -- Grammar Summary.md

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,8 @@ lines and uniform indentation with {BlockStringValue()}.
140140

141141
## Document Syntax
142142

143+
Description : StringValue
144+
143145
Document : Definition+
144146

145147
Definition :
@@ -156,7 +158,7 @@ ExecutableDefinition :
156158

157159
OperationDefinition :
158160

159-
- OperationType Name? VariablesDefinition? Directives? SelectionSet
161+
- Description? OperationType Name? VariablesDefinition? Directives? SelectionSet
160162
- SelectionSet
161163

162164
OperationType : one of `query` `mutation` `subscription`
@@ -181,8 +183,8 @@ FragmentSpread : ... FragmentName Directives?
181183

182184
InlineFragment : ... TypeCondition? Directives? SelectionSet
183185

184-
FragmentDefinition : fragment FragmentName TypeCondition Directives?
185-
SelectionSet
186+
FragmentDefinition : Description? fragment FragmentName TypeCondition
187+
Directives? SelectionSet
186188

187189
FragmentName : Name but not `on`
188190

@@ -220,7 +222,8 @@ ObjectField[Const] : Name : Value[?Const]
220222

221223
VariablesDefinition : ( VariableDefinition+ )
222224

223-
VariableDefinition : Variable : Type DefaultValue? Directives[Const]?
225+
VariableDefinition : Description? Variable : Type DefaultValue?
226+
Directives[Const]?
224227

225228
Variable : $ Name
226229

@@ -275,8 +278,6 @@ SchemaExtension :
275278

276279
RootOperationTypeDefinition : OperationType : NamedType
277280

278-
Description : StringValue
279-
280281
TypeDefinition :
281282

282283
- ScalarTypeDefinition

0 commit comments

Comments
 (0)