Skip to content

Commit 1347a1e

Browse files
leebyronleebyron
committed
move and minor edits
1 parent 3a9e537 commit 1347a1e

File tree

3 files changed

+189
-186
lines changed

3 files changed

+189
-186
lines changed

‎spec/Appendix B -- Grammar Summary.md‎

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -416,22 +416,29 @@ TypeSystemDirectiveLocation : one of
416416

417417
## Schema Coordinate Syntax
418418

419-
Note: In order to be unique, schema coordinates do not permit {Ignored} lexical
420-
grammars.
421-
SchemaCoordinate :
419+
Note: Schema coordinates must not contain {Ignored}.
420+
421+
SchemaCoordinateToken ::
422+
423+
- SchemaCoordinatePunctuator
424+
- Name
425+
426+
SchemaCoordinatePunctuator :: one of ( ) . : @
427+
428+
SchemaCoordinate ::
422429

423430
- TypeCoordinate
424431
- MemberCoordinate
425432
- ArgumentCoordinate
426433
- DirectiveCoordinate
427434
- DirectiveArgumentCoordinate
428435

429-
TypeCoordinate : Name
436+
TypeCoordinate :: Name
430437

431-
MemberCoordinate : Name . Name
438+
MemberCoordinate :: Name . Name
432439

433-
ArgumentCoordinate : Name . Name ( Name : )
440+
ArgumentCoordinate :: Name . Name ( Name : )
434441

435-
DirectiveCoordinate : @ Name
442+
DirectiveCoordinate :: @ Name
436443

437-
DirectiveArgumentCoordinate : @ Name ( Name : )
444+
DirectiveArgumentCoordinate :: @ Name ( Name : )

‎spec/Section 2 -- Language.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1377,3 +1377,177 @@ type Person
13771377
name: String
13781378
}
13791379
```
1380+
1381+
## Schema Coordinates
1382+
1383+
SchemaCoordinate ::
1384+
1385+
- TypeCoordinate
1386+
- MemberCoordinate
1387+
- ArgumentCoordinate
1388+
- DirectiveCoordinate
1389+
- DirectiveArgumentCoordinate
1390+
1391+
TypeCoordinate :: Name
1392+
1393+
MemberCoordinate :: Name . Name
1394+
1395+
ArgumentCoordinate :: Name . Name ( Name : )
1396+
1397+
DirectiveCoordinate :: @ Name
1398+
1399+
DirectiveArgumentCoordinate :: @ Name ( Name : )
1400+
1401+
:: A _schema coordinate_ is a human readable string that uniquely identifies a
1402+
_schema element_ within a GraphQL Schema.
1403+
1404+
:: A _schema element_ can be a named type, a field, an input field, an enum
1405+
value, a field argument, a directive, or a directive argument defined within a
1406+
schema (including built-in types and directives).
1407+
1408+
Note: Meta-fields are not defined within a schema, and thus are not _schema
1409+
element_. By extension, an introspection type is not a _schema element_.
1410+
1411+
:: The _containing element_ of a _schema element_ is the schema element with one
1412+
fewer {Name} token that syntactically contains it. Specifically:
1413+
1414+
- The containing element of an {ArgumentCoordinate} is a {MemberCoordinate}.
1415+
- The containing element of a {MemberCoordinate} is a {TypeCoordinate}.
1416+
- The containing element of a {DirectiveArgumentCoordinate} is a
1417+
{DirectiveCoordinate}.
1418+
- {TypeCoordinate} and {DirectiveCoordinate} have no containing element.
1419+
1420+
A _schema coordinate_ is always unique. Each _schema element_ can be referenced
1421+
by exactly one possible schema coordinate.
1422+
1423+
A _schema coordinate_ may refer to either a defined or built-in _schema
1424+
element_. For example, `String` and `@deprecated(reason:)` are both valid schema
1425+
coordinates which refer to built-in schema elements.
1426+
1427+
Note: A union member references a type in the schema. A type in the schema is
1428+
identified by a {TypeCoordinate}. There is no schema coordinate which indicates
1429+
a union member; this preserves the uniqueness property of a _schema coordinate_
1430+
as stated above.
1431+
1432+
Note: A {SchemaCoordinate} is not a definition within a GraphQL {Document}, but
1433+
a separate standalone grammar, intended to be used by tools to reference types,
1434+
fields, and other _schema element_. Examples include: references within
1435+
documentation to refer to types and fields in a schema, a lookup key that can be
1436+
used in logging tools to track how often particular fields are queried in
1437+
production.
1438+
1439+
**Parsing a Schema Coordinate**
1440+
1441+
SchemaCoordinateToken ::
1442+
1443+
- SchemaCoordinatePunctuator
1444+
- Name
1445+
1446+
SchemaCoordinatePunctuator :: one of ( ) . : @
1447+
1448+
A {SchemaCoordinate} is a self-contained grammar with its own set of lexical tokens. The source text of a
1449+
SchemaCoordinate must be a sequence of {SourceCharacter}.
1450+
1451+
Unlike [GraphQL documents](#sec-Language), {SchemaCoordinate} must not contain {Whitespace} or other {Ignored} grammars
1452+
within the character sequence. This
1453+
ensures that every schema coordinates has a single unambiguous and unique lexical form.
1454+
1455+
**Resolving a Schema Coordinate**
1456+
1457+
To refer to a _schema element_, a _schema coordinate_ must be interpreted in the
1458+
context of a GraphQL {schema}.
1459+
1460+
If the _schema element_ cannot be found, the resolve function will not yield a
1461+
value (without raising an error). However, an error will be raised if any
1462+
non-leaf nodes within a _schema coordinate_ cannot be found in the {schema}.
1463+
1464+
Note: Although it is syntactically possible to describe a meta-field or element
1465+
of the introspection schema with a schema coordinate (e.g. `Business.__typename`
1466+
or `__Type.fields(includeDeprecated:)`), they are not _schema element_ and
1467+
therefore resolving such coordinates does not have a defined behavior.
1468+
1469+
TypeCoordinate : Name
1470+
1471+
1. Let {typeName} be the value of {Name}.
1472+
2. Return the type in {schema} named {typeName} if it exists.
1473+
1474+
MemberCoordinate : Name . Name
1475+
1476+
1. Let {typeName} be the value of the first {Name}.
1477+
2. Let {type} be the type in {schema} named {typeName}.
1478+
3. Assert: {type} must exist, and must be an Enum, Input Object, Object or
1479+
Interface type.
1480+
4. If {type} is an Enum type:
1481+
1. Let {enumValueName} be the value of the second {Name}.
1482+
2. Return the enum value of {type} named {enumValueName} if it exists.
1483+
5. Otherwise, if {type} is an Input Object type:
1484+
1. Let {inputFieldName} be the value of the second {Name}.
1485+
2. Return the input field of {type} named {inputFieldName} if it exists.
1486+
6. Otherwise:
1487+
1. Let {fieldName} be the value of the second {Name}.
1488+
2. Return the field of {type} named {fieldName} if it exists.
1489+
1490+
ArgumentCoordinate : Name . Name ( Name : )
1491+
1492+
1. Let {typeName} be the value of the first {Name}.
1493+
2. Let {type} be the type in {schema} named {typeName}.
1494+
3. Assert: {type} must exist, and be an Object or Interface type.
1495+
4. Let {fieldName} be the value of the second {Name}.
1496+
5. Let {field} be the field of {type} named {fieldName}.
1497+
6. Assert: {field} must exist.
1498+
7. Let {fieldArgumentName} be the value of the third {Name}.
1499+
8. Return the argument of {field} named {fieldArgumentName} if it exists.
1500+
1501+
DirectiveCoordinate : @ Name
1502+
1503+
1. Let {directiveName} be the value of {Name}.
1504+
2. Return the directive in {schema} named {directiveName} if it exists.
1505+
1506+
DirectiveArgumentCoordinate : @ Name ( Name : )
1507+
1508+
1. Let {directiveName} be the value of the first {Name}.
1509+
2. Let {directive} be the directive in {schema} named {directiveName}.
1510+
3. Assert: {directive} must exist.
1511+
4. Let {directiveArgumentName} be the value of the second {Name}.
1512+
5. Return the argument of {directive} named {directiveArgumentName} if it
1513+
exists.
1514+
1515+
**Examples**
1516+
1517+
| Element Kind | _Schema Coordinate_ | _Schema Element_ |
1518+
| ------------------ | --------------------------------- | --------------------------------------------------------------------- |
1519+
| Named Type | `Business` | `Business` type |
1520+
| Field | `Business.name` | `name` field on the `Business` type |
1521+
| Input Field | `SearchCriteria.filter` | `filter` input field on the `SearchCriteria` input object type |
1522+
| Enum Value | `SearchFilter.OPEN_NOW` | `OPEN_NOW` value of the `SearchFilter` enum |
1523+
| Field Argument | `Query.searchBusiness(criteria:)` | `criteria` argument on the `searchBusiness` field on the `Query` type |
1524+
| Directive | `@private` | `@private` directive |
1525+
| Directive Argument | `@private(scope:)` | `scope` argument on the `@private` directive |
1526+
1527+
The table above shows an example of a _schema coordinate_ for every kind of
1528+
_schema element_ based on the schema below.
1529+
1530+
```graphql
1531+
type Query {
1532+
searchBusiness(criteria: SearchCriteria!): [Business]
1533+
}
1534+
1535+
input SearchCriteria {
1536+
name: String
1537+
filter: SearchFilter
1538+
}
1539+
1540+
enum SearchFilter {
1541+
OPEN_NOW
1542+
DELIVERS_TAKEOUT
1543+
VEGETARIAN_MENU
1544+
}
1545+
1546+
type Business {
1547+
id: ID
1548+
name: String
1549+
email: String @private(scope: "loggedIn")
1550+
}
1551+
1552+
directive @private(scope: String!) on FIELD_DEFINITION
1553+
```

‎spec/Section 3 -- Type System.md‎

Lines changed: 0 additions & 178 deletions
Original file line numberDiff line numberDiff line change
@@ -2227,181 +2227,3 @@ to the relevant IETF specification.
22272227
```graphql example
22282228
scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122")
22292229
```
2230-
2231-
## Schema Coordinates
2232-
2233-
SchemaCoordinate :
2234-
2235-
- TypeCoordinate
2236-
- MemberCoordinate
2237-
- ArgumentCoordinate
2238-
- DirectiveCoordinate
2239-
- DirectiveArgumentCoordinate
2240-
2241-
TypeCoordinate : Name
2242-
2243-
MemberCoordinate : Name . Name
2244-
2245-
ArgumentCoordinate : Name . Name ( Name : )
2246-
2247-
DirectiveCoordinate : @ Name
2248-
2249-
DirectiveArgumentCoordinate : @ Name ( Name : )
2250-
2251-
Note: A _schema coordinate_ is defined with its own grammar that, unlike GraphQL
2252-
documents, excludes {Ignored} lexical grammars (see: [Lexical Analysis &
2253-
Syntactic Parse of a Schema Coordinate](
2254-
(#sec-Type-System.Schema-Coordinates.Lexical-Analysis-Syntactic-Parse-of-a-Schema-Coordinate)).
2255-
2256-
:: A _schema coordinate_ is a human readable string that uniquely identifies a
2257-
_schema element_ within a GraphQL Schema.
2258-
2259-
:: A _schema element_ can be a named type, a field, an input field, an enum
2260-
value, a field argument, a directive, or a directive argument defined within a
2261-
schema (including built-in types and directives).
2262-
2263-
Note: Meta-fields are not defined within a schema, and thus are not _schema
2264-
element_. By extension, an introspection type is not a _schema element_.
2265-
2266-
:: The _containing element_ of a _schema element_ is the schema element with one
2267-
fewer {Name} token that syntactically contains it. Specifically:
2268-
2269-
- The containing element of an {ArgumentCoordinate} is a {MemberCoordinate}.
2270-
- The containing element of a {MemberCoordinate} is a {TypeCoordinate}.
2271-
- The containing element of a {DirectiveArgumentCoordinate} is a
2272-
{DirectiveCoordinate}.
2273-
- {TypeCoordinate} and {DirectiveCoordinate} have no containing element.
2274-
2275-
A _schema coordinate_ is always unique. Each _schema element_ can be referenced
2276-
by exactly one possible schema coordinate.
2277-
2278-
A _schema coordinate_ may refer to either a defined or built-in _schema
2279-
element_. For example, `String` and `@deprecated(reason:)` are both valid schema
2280-
coordinates which refer to built-in schema elements.
2281-
2282-
Note: A union member references a type in the schema. A type in the schema is
2283-
identified by a {TypeCoordinate}. There is no schema coordinate which indicates
2284-
a union member; this preserves the uniqueness property of a _schema coordinate_
2285-
as stated above.
2286-
2287-
Note: A {SchemaCoordinate} is not a definition within a GraphQL {Document}, but
2288-
a separate standalone grammar, intended to be used by tools to reference types,
2289-
fields, and other _schema element_. Examples include: references within
2290-
documentation to refer to types and fields in a schema, a lookup key that can be
2291-
used in logging tools to track how often particular fields are queried in
2292-
production.
2293-
2294-
**Lexical Analysis & Syntactic Parse of a Schema Coordinate**
2295-
2296-
Similar to [GraphQL documents](#sec-Language), a schema coordinate is defined as
2297-
a syntactic grammar where terminal symbols are tokens (indivisible lexical
2298-
units). These tokens are defined in a lexical grammar which matches patterns of
2299-
source characters. The source text of a schema coordinate must be a sequence of
2300-
{SourceCharacter}. The character sequence must be described by a sequence of
2301-
{Token} lexical grammars. The lexical token sequence, must be described by a
2302-
single {SchemaCoordinate} syntactic grammar.
2303-
2304-
Unlike with GraphQL documents, {Ignored} lexical grammars are not permitted
2305-
within the character sequence; a schema coordinate must therefore not contain
2306-
whitespace, line terminators, comments, commas, or a _Byte Order Mark_. This
2307-
constraint ensures that schema coordinates are both unambiguous and unique.
2308-
2309-
**Resolving a Schema Coordinate**
2310-
2311-
To refer to a _schema element_, a _schema coordinate_ must be interpreted in the
2312-
context of a GraphQL {schema}.
2313-
2314-
If the _schema element_ cannot be found, the resolve function will not yield a
2315-
value (without raising an error). However, an error will be raised if any
2316-
non-leaf nodes within a _schema coordinate_ cannot be found in the {schema}.
2317-
2318-
Note: Although it is syntactically possible to describe a meta-field or element
2319-
of the introspection schema with a schema coordinate (e.g. `Business.__typename`
2320-
or `__Type.fields(includeDeprecated:)`), they are not _schema element_ and
2321-
therefore resolving such coordinates results in implementation-defined behavior.
2322-
2323-
TypeCoordinate : Name
2324-
2325-
1. Let {typeName} be the value of {Name}.
2326-
2. Return the type in {schema} named {typeName} if it exists.
2327-
2328-
MemberCoordinate : Name . Name
2329-
2330-
1. Let {typeName} be the value of the first {Name}.
2331-
2. Let {type} be the type in {schema} named {typeName}.
2332-
3. Assert: {type} must exist, and must be an Enum, Input Object, Object or
2333-
Interface type.
2334-
4. If {type} is an Enum type:
2335-
1. Let {enumValueName} be the value of the second {Name}.
2336-
2. Return the enum value of {type} named {enumValueName} if it exists.
2337-
5. Otherwise, if {type} is an Input Object type:
2338-
1. Let {inputFieldName} be the value of the second {Name}.
2339-
2. Return the input field of {type} named {inputFieldName} if it exists.
2340-
6. Otherwise:
2341-
1. Let {fieldName} be the value of the second {Name}.
2342-
2. Return the field of {type} named {fieldName} if it exists.
2343-
2344-
ArgumentCoordinate : Name . Name ( Name : )
2345-
2346-
1. Let {typeName} be the value of the first {Name}.
2347-
2. Let {type} be the type in {schema} named {typeName}.
2348-
3. Assert: {type} must exist, and be an Object or Interface type.
2349-
4. Let {fieldName} be the value of the second {Name}.
2350-
5. Let {field} be the field of {type} named {fieldName}.
2351-
6. Assert: {field} must exist.
2352-
7. Let {fieldArgumentName} be the value of the third {Name}.
2353-
8. Return the argument of {field} named {fieldArgumentName} if it exists.
2354-
2355-
DirectiveCoordinate : @ Name
2356-
2357-
1. Let {directiveName} be the value of {Name}.
2358-
2. Return the directive in {schema} named {directiveName} if it exists.
2359-
2360-
DirectiveArgumentCoordinate : @ Name ( Name : )
2361-
2362-
1. Let {directiveName} be the value of the first {Name}.
2363-
2. Let {directive} be the directive in {schema} named {directiveName}.
2364-
3. Assert: {directive} must exist.
2365-
4. Let {directiveArgumentName} be the value of the second {Name}.
2366-
5. Return the argument of {directive} named {directiveArgumentName} if it
2367-
exists.
2368-
2369-
**Examples**
2370-
2371-
| Element Kind | _Schema Coordinate_ | _Schema Element_ |
2372-
| ------------------ | --------------------------------- | --------------------------------------------------------------------- |
2373-
| Named Type | `Business` | `Business` type |
2374-
| Field | `Business.name` | `name` field on the `Business` type |
2375-
| Input Field | `SearchCriteria.filter` | `filter` input field on the `SearchCriteria` input object type |
2376-
| Enum Value | `SearchFilter.OPEN_NOW` | `OPEN_NOW` value of the `SearchFilter` enum |
2377-
| Field Argument | `Query.searchBusiness(criteria:)` | `criteria` argument on the `searchBusiness` field on the `Query` type |
2378-
| Directive | `@private` | `@private` directive |
2379-
| Directive Argument | `@private(scope:)` | `scope` argument on the `@private` directive |
2380-
2381-
The table above shows an example of a _schema coordinate_ for every kind of
2382-
_schema element_ based on the schema below.
2383-
2384-
```graphql
2385-
type Query {
2386-
searchBusiness(criteria: SearchCriteria!): [Business]
2387-
}
2388-
2389-
input SearchCriteria {
2390-
name: String
2391-
filter: SearchFilter
2392-
}
2393-
2394-
enum SearchFilter {
2395-
OPEN_NOW
2396-
DELIVERS_TAKEOUT
2397-
VEGETARIAN_MENU
2398-
}
2399-
2400-
type Business {
2401-
id: ID
2402-
name: String
2403-
email: String @private(scope: "loggedIn")
2404-
}
2405-
2406-
directive @private(scope: String!) on FIELD_DEFINITION
2407-
```

0 commit comments

Comments
 (0)