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