From 38616cc645ce8ec739a82a059c54c1c129cb3383 Mon Sep 17 00:00:00 2001 From: Mark Larah Date: Thu, 17 Sep 2020 02:17:07 -0700 Subject: [PATCH 01/26] Add Schema Coordinates RFC --- spec/Appendix C -- Schema Coordinates.md | 168 +++++++++++++++++++++++ spec/GraphQL.md | 2 + 2 files changed, 170 insertions(+) create mode 100644 spec/Appendix C -- Schema Coordinates.md diff --git a/spec/Appendix C -- Schema Coordinates.md b/spec/Appendix C -- Schema Coordinates.md new file mode 100644 index 000000000..530f67aec --- /dev/null +++ b/spec/Appendix C -- Schema Coordinates.md @@ -0,0 +1,168 @@ +# Appendix: Schema Coordinates + +Schema Coordinates are human readable strings that uniquely identify an element defined in a GraphQL Schema. + +## Definition + +SchemaCoordinates : + - TypeName FieldSpecifier? + - InterfaceName FieldSpecifier? + - EnumName EnumValueSpecifier? + - @ DirectiveName ArgumentSpecifier? + - UnionName + +FieldSpecifier : + - . FieldName ArgumentSpecifier? + +ArgumentSpecifier : + - ( ArgumentName ) + +EnumValueSpecifier : + - . EnumValue + +## Examples + +This section shows example coordinates for the possible schema element types this syntax covers. + +All examples below will assume the following schema: + +```graphql example +directive @private(scope: String!) on FIELD + +interface Address { + city: String +} + +type User implements Address { + name: String + reviewCount: Int + friends: [User] + email: String @private(scope: 'loggedIn') + city: String +} + +type Business implements Address { + name: String + address: String + rating: Int + city: String +} + +union Entity = User | Business + +enum SearchFilter { + OPEN_NOW + DELIVERS_TAKEOUT + VEGETARIAN_MENU +} + +type Query { + searchBusiness(name: String!, filter: SearchFilter): Business +} +``` + +**Selecting a Type** + +Schema Coordinates for the `Business` type: + +```example +Business +``` + +Schema Coordinates for the `User` type: + +```example +User +``` + +**Selecting a Field on a Type** + +Schema Coordinates for the `name` field on the `Business` type: + +```example +Business.name +``` + +Schema Coordinates for the `name` field on the `User` type: + +```example +User.name +``` + +**Selecting an Argument on a Field** + +Schema Coordinates for the `name` argument on the `searchBusiness` field on the `Query` type: + +```example +Query.searchBusiness(name) +``` + +Schema Coordinates for the `filter` argument on the `searchBusiness` field on the `Query` type: + +```example +Query.searchBusiness(filter) +``` + +**Selecting an Enum** + +Schema Coordinates for the `SearchFilter` enum: + +```example +SearchFilter +``` + +**Selecting an Enum Value** + +Schema Coordinates for the `OPEN_NOW` value of the`SearchFilter` enum: + +```example +SearchFilter.OPEN_NOW +``` + +**Selecting a Directive Definition** + +Schema Coordinates for the `@private` directive definition: + +```example +@private +``` + +**Selecting a Directive Definition Argument** + +Schema Coordinates for the `scope` argument on the `@private` directive definition: + +```example +@private(scope) +``` + +**Selecting an Interface** + +Schema Coordinates for the `Address` interface: + +```example +Address +``` + +**Selecting a Field on an Interface** + +Schema Coordinates for the `city` field on the `Address` interface: + +```example +Address.city +``` + +**Selecting a Union** + +Schema Coordinates for the `Entity` union definition: + +```example +Entity +``` + +You may not select members inside a union definition. + +```graphql counter-example +Entity.Business +``` + +In such cases, you may wish to [select the type directly](#sec-Examples.Selecting-a-Type) instead. \ No newline at end of file diff --git a/spec/GraphQL.md b/spec/GraphQL.md index fad6bcdbe..aabff200e 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: Schema Coordinates](Appendix%20C%20--%20Schema%20Coordinates.md) From 45fb46cebd9035c98677dd0cb3f22e8891130ce7 Mon Sep 17 00:00:00 2001 From: Mark Larah Date: Tue, 17 Nov 2020 22:56:48 -0800 Subject: [PATCH 02/26] Update schema coordinates spec edit - Make examples table - Tweak the grammar definition --- spec/Appendix C -- Schema Coordinates.md | 125 +++++------------------ 1 file changed, 25 insertions(+), 100 deletions(-) diff --git a/spec/Appendix C -- Schema Coordinates.md b/spec/Appendix C -- Schema Coordinates.md index 530f67aec..aea21069e 100644 --- a/spec/Appendix C -- Schema Coordinates.md +++ b/spec/Appendix C -- Schema Coordinates.md @@ -5,17 +5,20 @@ Schema Coordinates are human readable strings that uniquely identify an element ## Definition SchemaCoordinates : - - TypeName FieldSpecifier? - - InterfaceName FieldSpecifier? + - TypeDefinitionName FieldSpecifier? - EnumName EnumValueSpecifier? - @ DirectiveName ArgumentSpecifier? - UnionName +TypeDefinitionName: + - ObjectTypeName + - InterfaceTypeName + FieldSpecifier : - . FieldName ArgumentSpecifier? ArgumentSpecifier : - - ( ArgumentName ) + - ( ArgumentName: ) EnumValueSpecifier : - . EnumValue @@ -61,108 +64,30 @@ type Query { } ``` -**Selecting a Type** - -Schema Coordinates for the `Business` type: - -```example -Business -``` - -Schema Coordinates for the `User` type: - -```example -User -``` - -**Selecting a Field on a Type** - -Schema Coordinates for the `name` field on the `Business` type: - -```example -Business.name -``` - -Schema Coordinates for the `name` field on the `User` type: +The following table demonstrates how to select various kinds of schema elements: -```example -User.name -``` - -**Selecting an Argument on a Field** - -Schema Coordinates for the `name` argument on the `searchBusiness` field on the `Query` type: - -```example -Query.searchBusiness(name) -``` - -Schema Coordinates for the `filter` argument on the `searchBusiness` field on the `Query` type: - -```example -Query.searchBusiness(filter) -``` - -**Selecting an Enum** - -Schema Coordinates for the `SearchFilter` enum: - -```example -SearchFilter -``` +| Example | Description | +| ------------------------------ | ------------------------------------------------------------------- | +| `Business` | `Business` type | +| `User` | `User` type | +| `Business.name` | `name` field on the `Business` type | +| `User.name` | `name` field on the `User` type | +| `Query.searchBusiness(name:)` | `name` argument on the `searchBusiness` field on the `Query` type | +| `Query.searchBusiness(filter:)`| `filter` argument on the `searchBusiness` field on the `Query` type | +| `SearchFilter` | `SearchFilter` enum | +| `SearchFilter.OPEN_NOW` | `OPEN_NOW` value of the`SearchFilter` enum | +| `@private` | `@private` directive definition | +| `@private(scope:)` | `scope` argument on the `@private` directive definition | +| `Address` | `Address` interface | +| `Address.city` | `city` field on the `Address` interface | +| `Entity` | `Entity` union definition | -**Selecting an Enum Value** - -Schema Coordinates for the `OPEN_NOW` value of the`SearchFilter` enum: - -```example -SearchFilter.OPEN_NOW -``` - -**Selecting a Directive Definition** - -Schema Coordinates for the `@private` directive definition: - -```example -@private -``` - -**Selecting a Directive Definition Argument** - -Schema Coordinates for the `scope` argument on the `@private` directive definition: - -```example -@private(scope) -``` - -**Selecting an Interface** - -Schema Coordinates for the `Address` interface: - -```example -Address -``` - -**Selecting a Field on an Interface** - -Schema Coordinates for the `city` field on the `Address` interface: - -```example -Address.city -``` - -**Selecting a Union** - -Schema Coordinates for the `Entity` union definition: - -```example -Entity -``` +Note: You may not select members inside a union definition. -You may not select members inside a union definition. +The following counter example are *not* considered valid Schema Coordinates: ```graphql counter-example Entity.Business ``` -In such cases, you may wish to [select the type directly](#sec-Examples.Selecting-a-Type) instead. \ No newline at end of file +In such cases, you may wish to select the type directly instead (e.g. `Business`). \ No newline at end of file From eabdaff30598e3dab34dc48ecaba0dacf583798c Mon Sep 17 00:00:00 2001 From: Mark Larah Date: Sat, 21 Nov 2020 12:12:06 -0800 Subject: [PATCH 03/26] implement PR suggestions - move schema coordinates to section 3.3.3 - add lee's grammar suggestion --- spec/Appendix C -- Schema Coordinates.md | 93 -------------- spec/GraphQL.md | 2 - spec/Section 3 -- Type System.md | 147 +++++++++++++++++++++++ 3 files changed, 147 insertions(+), 95 deletions(-) delete mode 100644 spec/Appendix C -- Schema Coordinates.md diff --git a/spec/Appendix C -- Schema Coordinates.md b/spec/Appendix C -- Schema Coordinates.md deleted file mode 100644 index aea21069e..000000000 --- a/spec/Appendix C -- Schema Coordinates.md +++ /dev/null @@ -1,93 +0,0 @@ -# Appendix: Schema Coordinates - -Schema Coordinates are human readable strings that uniquely identify an element defined in a GraphQL Schema. - -## Definition - -SchemaCoordinates : - - TypeDefinitionName FieldSpecifier? - - EnumName EnumValueSpecifier? - - @ DirectiveName ArgumentSpecifier? - - UnionName - -TypeDefinitionName: - - ObjectTypeName - - InterfaceTypeName - -FieldSpecifier : - - . FieldName ArgumentSpecifier? - -ArgumentSpecifier : - - ( ArgumentName: ) - -EnumValueSpecifier : - - . EnumValue - -## Examples - -This section shows example coordinates for the possible schema element types this syntax covers. - -All examples below will assume the following schema: - -```graphql example -directive @private(scope: String!) on FIELD - -interface Address { - city: String -} - -type User implements Address { - name: String - reviewCount: Int - friends: [User] - email: String @private(scope: 'loggedIn') - city: String -} - -type Business implements Address { - name: String - address: String - rating: Int - city: String -} - -union Entity = User | Business - -enum SearchFilter { - OPEN_NOW - DELIVERS_TAKEOUT - VEGETARIAN_MENU -} - -type Query { - searchBusiness(name: String!, filter: SearchFilter): Business -} -``` - -The following table demonstrates how to select various kinds of schema elements: - -| Example | Description | -| ------------------------------ | ------------------------------------------------------------------- | -| `Business` | `Business` type | -| `User` | `User` type | -| `Business.name` | `name` field on the `Business` type | -| `User.name` | `name` field on the `User` type | -| `Query.searchBusiness(name:)` | `name` argument on the `searchBusiness` field on the `Query` type | -| `Query.searchBusiness(filter:)`| `filter` argument on the `searchBusiness` field on the `Query` type | -| `SearchFilter` | `SearchFilter` enum | -| `SearchFilter.OPEN_NOW` | `OPEN_NOW` value of the`SearchFilter` enum | -| `@private` | `@private` directive definition | -| `@private(scope:)` | `scope` argument on the `@private` directive definition | -| `Address` | `Address` interface | -| `Address.city` | `city` field on the `Address` interface | -| `Entity` | `Entity` union definition | - -Note: You may not select members inside a union definition. - -The following counter example are *not* considered valid Schema Coordinates: - -```graphql counter-example -Entity.Business -``` - -In such cases, you may wish to select the type directly instead (e.g. `Business`). \ No newline at end of file diff --git a/spec/GraphQL.md b/spec/GraphQL.md index aabff200e..fad6bcdbe 100644 --- a/spec/GraphQL.md +++ b/spec/GraphQL.md @@ -139,5 +139,3 @@ 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: Schema Coordinates](Appendix%20C%20--%20Schema%20Coordinates.md) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 1348899fb..1ec512ab5 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -282,6 +282,153 @@ Schema extensions have the potential to be invalid if incorrectly defined. 2. Any non-repeatable directives provided must not already apply to the original Schema. +### Schema Coordinates + +Schema Coordinates are human readable strings that uniquely identify an element defined in a GraphQL Schema. + +**Definition** + +SchemaCoordinate: + - Name + - Name . Name + - Name . Name ( Name : ) + - @ Name + - @ Name ( Name : ) + +**Semantics** + +SchemaCoordinate: Name + 1. Let {typeName} be the value of the first {Name}. + 2. Return the type in the schema named {typeName}. + +SchemaCoordinate: Name . Name + 1. Let {typeName} be the value of the first {Name}. + 2. Let {type} be the type in the schema named {typeName}. + 3. If {type} is an Enum type: + 1. Let {enumName} be the value of the second {Name}. + 2. Return the enum value of {type} named {enumName}. + 4. Otherwise if {type} is an Input Object type: + 1. Let {inputFieldName} be the value of the second {Name}. + 2. Return the input field of {type} named {inputFieldName}. + 5. Otherwise {type} must be an Object or Interface type: + 1. Let {fieldName} be the value of the second {Name}. + 2. Return the field of {type} named {fieldName}. + +SchemaCoordinate: Name . Name ( Name : ) + 1. Let {typeName} be the value of the first {Name}. + 2. Let {type} be the type in the schema named {typeName}. + 3. Assert: {type} must be an Object or Interface type. + 4. Let {fieldName} be the value of the second {Name}. + 5. Let {field} be the field of {type} named {fieldName}. + 6. Assert: {field} must exist. + 7. Let {argumentName} be the value of the third {Name}. + 8. Return the argument of {field} named {argumentName}. + +SchemaCoordinate: @ Name + 1. Let {directiveName} be the value of the first {Name}. + 2. Return the directive in the schema named {directiveName}. + +SchemaCoordinate: @ Name ( Name : ) + 1. Let {directiveName} be the value of the first {Name}. + 2. Let {directive} be the directive in the schema named {directiveName}. + 3. Assert: {directive} must exist. + 7. Let {argumentName} be the value of the second {Name}. + 8. Return the argument of {directive} named {argumentName} + +**Examples** + +This section shows example coordinates for the possible schema element types this syntax covers. + +All examples below will assume the following schema: + +```graphql example +directive @private(scope: String!) on FIELD + +scalar DateTime + +input ReviewInput { + content: String + author: String + businessId: String +} + +interface Address { + city: String +} + +type User implements Address { + name: String + reviewCount: Int + friends: [User] + email: String @private(scope: "loggedIn") + city: String +} + +type Business implements Address { + name: String + address: String + rating: Int + city: String + reviews: [Review] + createdAt: DateTime +} + +type Review { + content: String + author: User + business: Business + createdAt: DateTime +} + +union Entity = User | Business | Review + +enum SearchFilter { + OPEN_NOW + DELIVERS_TAKEOUT + VEGETARIAN_MENU +} + +type Query { + searchBusiness(name: String!, filter: SearchFilter): Business +} + +type Mutation { + addReview(input: ReviewInput!): Review +} +``` + +The following table demonstrates how to select various kinds of schema elements: + +| Example | Description | +| ------------------------------ | ------------------------------------------------------------------- | +| `Business` | `Business` type | +| `User` | `User` type | +| `Business.name` | `name` field on the `Business` type | +| `User.name` | `name` field on the `User` type | +| `Query.searchBusiness(name:)` | `name` argument on the `searchBusiness` field on the `Query` type | +| `Query.searchBusiness(filter:)`| `filter` argument on the `searchBusiness` field on the `Query` type | +| `SearchFilter` | `SearchFilter` enum | +| `SearchFilter.OPEN_NOW` | `OPEN_NOW` value of the`SearchFilter` enum | +| `@private` | `@private` directive definition | +| `@private(scope:)` | `scope` argument on the `@private` directive definition | +| `Address` | `Address` interface | +| `Address.city` | `city` field on the `Address` interface | +| `ReviewInput` | `ReviewInput` input object type | +| `ReviewInput.author` | `author` field on the `ReviewInput` input object type | +| `Entity` | `Entity` union definition | +| `DateTime` | Custom `DateTime` scalar type | +| `String` | Built-in `String` scalar type | + +Note: You may not select members inside a union definition. + +The following counter example is *not* considered a valid Schema Coordinate: + +```graphql counter-example +Entity.Business +``` + +In such cases, you may wish to select the type directly instead (e.g. `Business`). + ## Types TypeDefinition : From f994f99c714a5d7975872b8ee158d1e9b3be4e7e Mon Sep 17 00:00:00 2001 From: Mark Larah Date: Sun, 22 Nov 2020 11:43:45 -0800 Subject: [PATCH 04/26] Tweak example table wording --- spec/Section 3 -- Type System.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 1ec512ab5..d6381fad9 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -397,9 +397,9 @@ type Mutation { } ``` -The following table demonstrates how to select various kinds of schema elements: +The following table demonstrates how to select various kinds of schema members: -| Example | Description | +| Schema Coordinate | Description | | ------------------------------ | ------------------------------------------------------------------- | | `Business` | `Business` type | | `User` | `User` type | From 17002d489121b8a59a0ba8fb5576f27005aebe66 Mon Sep 17 00:00:00 2001 From: Mark Larah Date: Mon, 23 Nov 2020 12:47:27 -0800 Subject: [PATCH 05/26] Apply suggestions from code review Co-authored-by: Benjie Gillam --- spec/Section 3 -- Type System.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index d6381fad9..a3c6b61b1 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -310,9 +310,10 @@ SchemaCoordinate: Name . Name 4. Otherwise if {type} is an Input Object type: 1. Let {inputFieldName} be the value of the second {Name}. 2. Return the input field of {type} named {inputFieldName}. - 5. Otherwise {type} must be an Object or Interface type: - 1. Let {fieldName} be the value of the second {Name}. - 2. Return the field of {type} named {fieldName}. + 5. Otherwise: + 1. Assert: {type} must be an Object or Interface type. + 2. Let {fieldName} be the value of the second {Name}. + 3. Return the field of {type} named {fieldName}. SchemaCoordinate: Name . Name ( Name : ) 1. Let {typeName} be the value of the first {Name}. @@ -414,7 +415,7 @@ The following table demonstrates how to select various kinds of schema members: | `Address` | `Address` interface | | `Address.city` | `city` field on the `Address` interface | | `ReviewInput` | `ReviewInput` input object type | -| `ReviewInput.author` | `author` field on the `ReviewInput` input object type | +| `ReviewInput.author` | `author` input field on the `ReviewInput` input object type | | `Entity` | `Entity` union definition | | `DateTime` | Custom `DateTime` scalar type | | `String` | Built-in `String` scalar type | From 6456c5f432225b446d685911272c7ea490d72ab6 Mon Sep 17 00:00:00 2001 From: Mark Larah Date: Sat, 28 Nov 2020 00:20:57 -0800 Subject: [PATCH 06/26] enumName -> enumValueName --- spec/Section 3 -- Type System.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index a3c6b61b1..1e001033f 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -305,8 +305,8 @@ SchemaCoordinate: Name . Name 1. Let {typeName} be the value of the first {Name}. 2. Let {type} be the type in the schema named {typeName}. 3. If {type} is an Enum type: - 1. Let {enumName} be the value of the second {Name}. - 2. Return the enum value of {type} named {enumName}. + 1. Let {enumValueName} be the value of the second {Name}. + 2. Return the enum value of {type} named {enumValueName}. 4. Otherwise if {type} is an Input Object type: 1. Let {inputFieldName} be the value of the second {Name}. 2. Return the input field of {type} named {inputFieldName}. From 49059778dedf8d2f278c50d5885a7edb9e679852 Mon Sep 17 00:00:00 2001 From: Mark Larah Date: Mon, 4 Jan 2021 00:11:51 -0800 Subject: [PATCH 07/26] - Add PR feedback - remove extraneous examples - tighten up wording --- spec/Section 3 -- Type System.md | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 1e001033f..868d01be2 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -284,7 +284,8 @@ Schema extensions have the potential to be invalid if incorrectly defined. ### Schema Coordinates -Schema Coordinates are human readable strings that uniquely identify an element defined in a GraphQL Schema. +Schema Coordinates are human readable strings that uniquely identify a specific +type, field, argument, enum value, or directive defined in a GraphQL Schema. **Definition** @@ -295,6 +296,12 @@ SchemaCoordinate: - @ Name - @ Name ( Name : ) +Note: The `SchemaCoordinate` syntax is not part of a GraphQL Document. Schema +Coordinates are a separate syntax, intended to be used by tooling when +referencing types and fields or other schema elements. (For example, a server +that wishes to keep track of the number of times fields have been accessed may +use their Schema Coordinate as the lookup key.) + **Semantics** SchemaCoordinate: Name @@ -338,7 +345,8 @@ SchemaCoordinate: @ Name ( Name : ) **Examples** -This section shows example coordinates for the possible schema element types this syntax covers. +This section shows example coordinates for the possible schema element types +this syntax covers. All examples below will assume the following schema: @@ -398,16 +406,14 @@ type Mutation { } ``` -The following table demonstrates how to select various kinds of schema members: +The following table shows examples of Schema Coordinates for elements in the +schema above: | Schema Coordinate | Description | | ------------------------------ | ------------------------------------------------------------------- | | `Business` | `Business` type | -| `User` | `User` type | -| `Business.name` | `name` field on the `Business` type | | `User.name` | `name` field on the `User` type | | `Query.searchBusiness(name:)` | `name` argument on the `searchBusiness` field on the `Query` type | -| `Query.searchBusiness(filter:)`| `filter` argument on the `searchBusiness` field on the `Query` type | | `SearchFilter` | `SearchFilter` enum | | `SearchFilter.OPEN_NOW` | `OPEN_NOW` value of the`SearchFilter` enum | | `@private` | `@private` directive definition | @@ -420,15 +426,19 @@ The following table demonstrates how to select various kinds of schema members: | `DateTime` | Custom `DateTime` scalar type | | `String` | Built-in `String` scalar type | -Note: You may not select members inside a union definition. +Schema Coordinates are always unique. Each type, field, argument, enum value, or +directive may be referenced by exactly one possible Schema Coordinate. -The following counter example is *not* considered a valid Schema Coordinate: +For example, the following is *not* a valid Schema Coordinate: ```graphql counter-example Entity.Business ``` -In such cases, you may wish to select the type directly instead (e.g. `Business`). +In this counter example, both `Entity.Business` and `Business` would refer to +the `Business` type. Since it would be ambiguous what the "primary key" should +be in an application that uses Schema Coordinates to reference types, this is +not allowed. ## Types From 8be29ca0253d0453633b48429884320d6d8cf131 Mon Sep 17 00:00:00 2001 From: Mark Larah Date: Thu, 7 Jan 2021 11:11:46 -0800 Subject: [PATCH 08/26] Update Section 3 -- Type System.md --- spec/Section 3 -- Type System.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 868d01be2..a035381e6 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -435,10 +435,10 @@ For example, the following is *not* a valid Schema Coordinate: Entity.Business ``` -In this counter example, both `Entity.Business` and `Business` would refer to -the `Business` type. Since it would be ambiguous what the "primary key" should -be in an application that uses Schema Coordinates to reference types, this is -not allowed. +In this counter example, `Entity.Business` is redundant since `Business` already +uniquely identifies the Business type. Such redundancy is disallowed by this +spec - every type, field, field argument, enum value, directive, and directive +argument has exactly one canonical Schema Coordinate. ## Types From 568d26f4ed13c9d01b585a2fb97f6223fe1d89d8 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Tue, 13 Apr 2021 14:34:26 -0700 Subject: [PATCH 09/26] Editorial on grammar and semantics --- spec/Appendix B -- Grammar Summary.md | 7 ++++ spec/Section 3 -- Type System.md | 48 +++++++++++++-------------- 2 files changed, 31 insertions(+), 24 deletions(-) diff --git a/spec/Appendix B -- Grammar Summary.md b/spec/Appendix B -- Grammar Summary.md index 92f222cb3..11ceaecab 100644 --- a/spec/Appendix B -- Grammar Summary.md +++ b/spec/Appendix B -- Grammar Summary.md @@ -268,6 +268,13 @@ SchemaExtension : RootOperationTypeDefinition : OperationType : NamedType +SchemaCoordinate : + - Name + - Name . Name + - Name . Name ( Name : ) + - @ Name + - @ Name ( Name : ) + Description : StringValue TypeDefinition : diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index a035381e6..745f9815f 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -287,30 +287,30 @@ Schema extensions have the potential to be invalid if incorrectly defined. Schema Coordinates are human readable strings that uniquely identify a specific type, field, argument, enum value, or directive defined in a GraphQL Schema. -**Definition** - -SchemaCoordinate: +SchemaCoordinate : - Name - Name . Name - Name . Name ( Name : ) - @ Name - @ Name ( Name : ) -Note: The `SchemaCoordinate` syntax is not part of a GraphQL Document. Schema -Coordinates are a separate syntax, intended to be used by tooling when -referencing types and fields or other schema elements. (For example, a server -that wishes to keep track of the number of times fields have been accessed may -use their Schema Coordinate as the lookup key.) +Note: A {SchemaCoordinate} is not a definition within a GraphQL {Document}. +Schema coordinates are a separate syntax, intended to be used by tools to +reference types and fields or other schema elements. For example: within +documentation, or as lookup keys a service uses to track usage frequency. **Semantics** -SchemaCoordinate: Name +A schema coordinate's semantics assume they are interpreted in the context of +a single GraphQL {schema}. + +SchemaCoordinate : Name 1. Let {typeName} be the value of the first {Name}. - 2. Return the type in the schema named {typeName}. + 2. Return the type in the {schema} named {typeName}. -SchemaCoordinate: Name . Name +SchemaCoordinate : Name . Name 1. Let {typeName} be the value of the first {Name}. - 2. Let {type} be the type in the schema named {typeName}. + 2. Let {type} be the type in the {schema} named {typeName}. 3. If {type} is an Enum type: 1. Let {enumValueName} be the value of the second {Name}. 2. Return the enum value of {type} named {enumValueName}. @@ -318,30 +318,30 @@ SchemaCoordinate: Name . Name 1. Let {inputFieldName} be the value of the second {Name}. 2. Return the input field of {type} named {inputFieldName}. 5. Otherwise: - 1. Assert: {type} must be an Object or Interface type. + 1. Assert {type} must be an Object or Interface type. 2. Let {fieldName} be the value of the second {Name}. 3. Return the field of {type} named {fieldName}. - -SchemaCoordinate: Name . Name ( Name : ) + +SchemaCoordinate : Name . Name ( Name : ) 1. Let {typeName} be the value of the first {Name}. - 2. Let {type} be the type in the schema named {typeName}. - 3. Assert: {type} must be an Object or Interface type. + 2. Let {type} be the type in the {schema} named {typeName}. + 3. Assert {type} must be an Object or Interface type. 4. Let {fieldName} be the value of the second {Name}. 5. Let {field} be the field of {type} named {fieldName}. - 6. Assert: {field} must exist. + 6. Assert {field} must exist. 7. Let {argumentName} be the value of the third {Name}. 8. Return the argument of {field} named {argumentName}. -SchemaCoordinate: @ Name +SchemaCoordinate : @ Name 1. Let {directiveName} be the value of the first {Name}. - 2. Return the directive in the schema named {directiveName}. + 2. Return the directive in the {schema} named {directiveName}. -SchemaCoordinate: @ Name ( Name : ) +SchemaCoordinate : @ Name ( Name : ) 1. Let {directiveName} be the value of the first {Name}. - 2. Let {directive} be the directive in the schema named {directiveName}. - 3. Assert: {directive} must exist. + 2. Let {directive} be the directive in the {schema} named {directiveName}. + 3. Assert {directive} must exist. 7. Let {argumentName} be the value of the second {Name}. - 8. Return the argument of {directive} named {argumentName} + 8. Return the argument of {directive} named {argumentName}. **Examples** From b8f3f4709cf48356ab3ab12b81be8781baba6121 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Tue, 13 Apr 2021 16:52:38 -0700 Subject: [PATCH 10/26] Move section --- spec/Appendix B -- Grammar Summary.md | 14 +- spec/Section 3 -- Type System.md | 315 +++++++++++++------------- 2 files changed, 165 insertions(+), 164 deletions(-) diff --git a/spec/Appendix B -- Grammar Summary.md b/spec/Appendix B -- Grammar Summary.md index 11ceaecab..e42bd7953 100644 --- a/spec/Appendix B -- Grammar Summary.md +++ b/spec/Appendix B -- Grammar Summary.md @@ -268,13 +268,6 @@ SchemaExtension : RootOperationTypeDefinition : OperationType : NamedType -SchemaCoordinate : - - Name - - Name . Name - - Name . Name ( Name : ) - - @ Name - - @ Name ( Name : ) - Description : StringValue TypeDefinition : @@ -419,3 +412,10 @@ TypeSystemDirectiveLocation : one of - `ENUM_VALUE` - `INPUT_OBJECT` - `INPUT_FIELD_DEFINITION` + +SchemaCoordinate : +- Name +- Name . Name +- Name . Name ( Name : ) +- @ Name +- @ Name ( Name : ) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 745f9815f..77e482b3f 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -282,163 +282,6 @@ Schema extensions have the potential to be invalid if incorrectly defined. 2. Any non-repeatable directives provided must not already apply to the original Schema. -### Schema Coordinates - -Schema Coordinates are human readable strings that uniquely identify a specific -type, field, argument, enum value, or directive defined in a GraphQL Schema. - -SchemaCoordinate : - - Name - - Name . Name - - Name . Name ( Name : ) - - @ Name - - @ Name ( Name : ) - -Note: A {SchemaCoordinate} is not a definition within a GraphQL {Document}. -Schema coordinates are a separate syntax, intended to be used by tools to -reference types and fields or other schema elements. For example: within -documentation, or as lookup keys a service uses to track usage frequency. - -**Semantics** - -A schema coordinate's semantics assume they are interpreted in the context of -a single GraphQL {schema}. - -SchemaCoordinate : Name - 1. Let {typeName} be the value of the first {Name}. - 2. Return the type in the {schema} named {typeName}. - -SchemaCoordinate : Name . Name - 1. Let {typeName} be the value of the first {Name}. - 2. Let {type} be the type in the {schema} named {typeName}. - 3. If {type} is an Enum type: - 1. Let {enumValueName} be the value of the second {Name}. - 2. Return the enum value of {type} named {enumValueName}. - 4. Otherwise if {type} is an Input Object type: - 1. Let {inputFieldName} be the value of the second {Name}. - 2. Return the input field of {type} named {inputFieldName}. - 5. Otherwise: - 1. Assert {type} must be an Object or Interface type. - 2. Let {fieldName} be the value of the second {Name}. - 3. Return the field of {type} named {fieldName}. - -SchemaCoordinate : Name . Name ( Name : ) - 1. Let {typeName} be the value of the first {Name}. - 2. Let {type} be the type in the {schema} named {typeName}. - 3. Assert {type} must be an Object or Interface type. - 4. Let {fieldName} be the value of the second {Name}. - 5. Let {field} be the field of {type} named {fieldName}. - 6. Assert {field} must exist. - 7. Let {argumentName} be the value of the third {Name}. - 8. Return the argument of {field} named {argumentName}. - -SchemaCoordinate : @ Name - 1. Let {directiveName} be the value of the first {Name}. - 2. Return the directive in the {schema} named {directiveName}. - -SchemaCoordinate : @ Name ( Name : ) - 1. Let {directiveName} be the value of the first {Name}. - 2. Let {directive} be the directive in the {schema} named {directiveName}. - 3. Assert {directive} must exist. - 7. Let {argumentName} be the value of the second {Name}. - 8. Return the argument of {directive} named {argumentName}. - -**Examples** - -This section shows example coordinates for the possible schema element types -this syntax covers. - -All examples below will assume the following schema: - -```graphql example -directive @private(scope: String!) on FIELD - -scalar DateTime - -input ReviewInput { - content: String - author: String - businessId: String -} - -interface Address { - city: String -} - -type User implements Address { - name: String - reviewCount: Int - friends: [User] - email: String @private(scope: "loggedIn") - city: String -} - -type Business implements Address { - name: String - address: String - rating: Int - city: String - reviews: [Review] - createdAt: DateTime -} - -type Review { - content: String - author: User - business: Business - createdAt: DateTime -} - -union Entity = User | Business | Review - -enum SearchFilter { - OPEN_NOW - DELIVERS_TAKEOUT - VEGETARIAN_MENU -} - -type Query { - searchBusiness(name: String!, filter: SearchFilter): Business -} - -type Mutation { - addReview(input: ReviewInput!): Review -} -``` - -The following table shows examples of Schema Coordinates for elements in the -schema above: - -| Schema Coordinate | Description | -| ------------------------------ | ------------------------------------------------------------------- | -| `Business` | `Business` type | -| `User.name` | `name` field on the `User` type | -| `Query.searchBusiness(name:)` | `name` argument on the `searchBusiness` field on the `Query` type | -| `SearchFilter` | `SearchFilter` enum | -| `SearchFilter.OPEN_NOW` | `OPEN_NOW` value of the`SearchFilter` enum | -| `@private` | `@private` directive definition | -| `@private(scope:)` | `scope` argument on the `@private` directive definition | -| `Address` | `Address` interface | -| `Address.city` | `city` field on the `Address` interface | -| `ReviewInput` | `ReviewInput` input object type | -| `ReviewInput.author` | `author` input field on the `ReviewInput` input object type | -| `Entity` | `Entity` union definition | -| `DateTime` | Custom `DateTime` scalar type | -| `String` | Built-in `String` scalar type | - -Schema Coordinates are always unique. Each type, field, argument, enum value, or -directive may be referenced by exactly one possible Schema Coordinate. - -For example, the following is *not* a valid Schema Coordinate: - -```graphql counter-example -Entity.Business -``` - -In this counter example, `Entity.Business` is redundant since `Business` already -uniquely identifies the Business type. Such redundancy is disallowed by this -spec - every type, field, field argument, enum value, directive, and directive -argument has exactly one canonical Schema Coordinate. ## Types @@ -2322,3 +2165,161 @@ to the relevant IETF specification. ```graphql example scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122") ``` + +## Schema Coordinates + +Schema Coordinates are human readable strings that uniquely identify a specific +type, field, argument, enum value, or directive defined in a GraphQL Schema. + +SchemaCoordinate : + - Name + - Name . Name + - Name . Name ( Name : ) + - @ Name + - @ Name ( Name : ) + +Note: A {SchemaCoordinate} is not a definition within a GraphQL {Document}. +Schema coordinates are a separate syntax, intended to be used by tools to +reference types and fields or other schema elements. For example: within +documentation, or as lookup keys a service uses to track usage frequency. + +**Semantics** + +A schema coordinate's semantics assume they are interpreted in the context of +a single GraphQL {schema}. + +SchemaCoordinate : Name + 1. Let {typeName} be the value of the first {Name}. + 2. Return the type in the {schema} named {typeName}. + +SchemaCoordinate : Name . Name + 1. Let {typeName} be the value of the first {Name}. + 2. Let {type} be the type in the {schema} named {typeName}. + 3. If {type} is an Enum type: + 1. Let {enumValueName} be the value of the second {Name}. + 2. Return the enum value of {type} named {enumValueName}. + 4. Otherwise if {type} is an Input Object type: + 1. Let {inputFieldName} be the value of the second {Name}. + 2. Return the input field of {type} named {inputFieldName}. + 5. Otherwise: + 1. Assert {type} must be an Object or Interface type. + 2. Let {fieldName} be the value of the second {Name}. + 3. Return the field of {type} named {fieldName}. + +SchemaCoordinate : Name . Name ( Name : ) + 1. Let {typeName} be the value of the first {Name}. + 2. Let {type} be the type in the {schema} named {typeName}. + 3. Assert {type} must be an Object or Interface type. + 4. Let {fieldName} be the value of the second {Name}. + 5. Let {field} be the field of {type} named {fieldName}. + 6. Assert {field} must exist. + 7. Let {argumentName} be the value of the third {Name}. + 8. Return the argument of {field} named {argumentName}. + +SchemaCoordinate : @ Name + 1. Let {directiveName} be the value of the first {Name}. + 2. Return the directive in the {schema} named {directiveName}. + +SchemaCoordinate : @ Name ( Name : ) + 1. Let {directiveName} be the value of the first {Name}. + 2. Let {directive} be the directive in the {schema} named {directiveName}. + 3. Assert {directive} must exist. + 7. Let {argumentName} be the value of the second {Name}. + 8. Return the argument of {directive} named {argumentName}. + +**Examples** + +This section shows example coordinates for the possible schema element types +this syntax covers. + +All examples below will assume the following schema: + +```graphql example +directive @private(scope: String!) on FIELD + +scalar DateTime + +input ReviewInput { + content: String + author: String + businessId: String +} + +interface Address { + city: String +} + +type User implements Address { + name: String + reviewCount: Int + friends: [User] + email: String @private(scope: "loggedIn") + city: String +} + +type Business implements Address { + name: String + address: String + rating: Int + city: String + reviews: [Review] + createdAt: DateTime +} + +type Review { + content: String + author: User + business: Business + createdAt: DateTime +} + +union Entity = User | Business | Review + +enum SearchFilter { + OPEN_NOW + DELIVERS_TAKEOUT + VEGETARIAN_MENU +} + +type Query { + searchBusiness(name: String!, filter: SearchFilter): Business +} + +type Mutation { + addReview(input: ReviewInput!): Review +} +``` + +The following table shows examples of Schema Coordinates for elements in the +schema above: + +| Schema Coordinate | Description | +| ------------------------------ | ------------------------------------------------------------------- | +| `Business` | `Business` type | +| `User.name` | `name` field on the `User` type | +| `Query.searchBusiness(name:)` | `name` argument on the `searchBusiness` field on the `Query` type | +| `SearchFilter` | `SearchFilter` enum | +| `SearchFilter.OPEN_NOW` | `OPEN_NOW` value of the`SearchFilter` enum | +| `@private` | `@private` directive definition | +| `@private(scope:)` | `scope` argument on the `@private` directive definition | +| `Address` | `Address` interface | +| `Address.city` | `city` field on the `Address` interface | +| `ReviewInput` | `ReviewInput` input object type | +| `ReviewInput.author` | `author` input field on the `ReviewInput` input object type | +| `Entity` | `Entity` union definition | +| `DateTime` | Custom `DateTime` scalar type | +| `String` | Built-in `String` scalar type | + +Schema Coordinates are always unique. Each type, field, argument, enum value, or +directive may be referenced by exactly one possible Schema Coordinate. + +For example, the following is *not* a valid Schema Coordinate: + +```graphql counter-example +Entity.Business +``` + +In this counter example, `Entity.Business` is redundant since `Business` already +uniquely identifies the Business type. Such redundancy is disallowed by this +spec - every type, field, field argument, enum value, directive, and directive +argument has exactly one canonical Schema Coordinate. From 85801629d9c2b7a2c6983f74f6afefc268efbdca Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Tue, 13 Apr 2021 17:59:55 -0700 Subject: [PATCH 11/26] Simplify examples --- spec/Section 3 -- Type System.md | 135 ++++++++++--------------------- 1 file changed, 44 insertions(+), 91 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 77e482b3f..8e2b5e08e 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2168,9 +2168,6 @@ scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122") ## Schema Coordinates -Schema Coordinates are human readable strings that uniquely identify a specific -type, field, argument, enum value, or directive defined in a GraphQL Schema. - SchemaCoordinate : - Name - Name . Name @@ -2178,15 +2175,28 @@ SchemaCoordinate : - @ Name - @ Name ( Name : ) -Note: A {SchemaCoordinate} is not a definition within a GraphQL {Document}. -Schema coordinates are a separate syntax, intended to be used by tools to -reference types and fields or other schema elements. For example: within -documentation, or as lookup keys a service uses to track usage frequency. +:: A *schema coordinate* is a human readable string that uniquely identifies a +*schema element* within a GraphQL Schema. + +:: A *schema element* is a specific instance of a named type, type field, +input field, enum value, field argument, directive, or directive argument. + +A *schema coordinate* is always unique. Each *schema element* may be referenced +by exactly one possible schema coordinate. + +A *schema coordinate* may refer to either a defined or built-in *schema element*. +For example, `String` and `@deprecated(reason:)` are both valid schema +coordinates which refer to built-in schema elements. + +Note: A {SchemaCoordinate} is not a definition within a GraphQL {Document}, but +a separate stand-alone grammar, intended to be used by tools to reference types, +fields, and other *schema element*s. For example as references within +documentation, or as lookup keys in usage frequency tracking. **Semantics** -A schema coordinate's semantics assume they are interpreted in the context of -a single GraphQL {schema}. +To refer to a *schema element*, a *schema coordinate* must be interpreted in the +context of a GraphQL {schema}. SchemaCoordinate : Name 1. Let {typeName} be the value of the first {Name}. @@ -2229,97 +2239,40 @@ SchemaCoordinate : @ Name ( Name : ) **Examples** -This section shows example coordinates for the possible schema element types -this syntax covers. +| Element Kind | *Schema Coordinate* | *Schema Element* | +| ------------------ | -------------------------------- | ----------------------------------------------------------------------- | +| Named Type | `Business` | `Business` type | +| Type Field | `Business.name` | `name` field on the `Business` type | +| Input Field | `SearchCriteria.filter` | `filter` input field on the `SearchCriteria` input object type | +| Enum Value | `SearchFilter.OPEN_NOW` | `OPEN_NOW` value of the `SearchFilter` enum | +| Field Argument | `Query.searchBusiness(criteria:)`| `criteria` argument on the `searchBusiness` field on the `Query` type | +| Directive | `@private` | `@private` directive | +| Directive Argument | `@private(scope:)` | `scope` argument on the `@private` directive | -All examples below will assume the following schema: +The table above shows an example of a *schema coordinate* for every kind of +*schema element* based on the schema below. -```graphql example -directive @private(scope: String!) on FIELD - -scalar DateTime - -input ReviewInput { - content: String - author: String - businessId: String -} - -interface Address { - city: String -} - -type User implements Address { - name: String - reviewCount: Int - friends: [User] - email: String @private(scope: "loggedIn") - city: String -} - -type Business implements Address { - name: String - address: String - rating: Int - city: String - reviews: [Review] - createdAt: DateTime +```graphql +type Query { + searchBusiness(criteria: SearchCriteria!): [Business] } -type Review { - content: String - author: User - business: Business - createdAt: DateTime +input SearchCriteria { + name: String + filter: SearchFilter } -union Entity = User | Business | Review - enum SearchFilter { - OPEN_NOW - DELIVERS_TAKEOUT - VEGETARIAN_MENU -} - -type Query { - searchBusiness(name: String!, filter: SearchFilter): Business + OPEN_NOW + DELIVERS_TAKEOUT + VEGETARIAN_MENU } -type Mutation { - addReview(input: ReviewInput!): Review +type Business { + id: ID + name: String + email: String @private(scope: "loggedIn") } -``` - -The following table shows examples of Schema Coordinates for elements in the -schema above: - -| Schema Coordinate | Description | -| ------------------------------ | ------------------------------------------------------------------- | -| `Business` | `Business` type | -| `User.name` | `name` field on the `User` type | -| `Query.searchBusiness(name:)` | `name` argument on the `searchBusiness` field on the `Query` type | -| `SearchFilter` | `SearchFilter` enum | -| `SearchFilter.OPEN_NOW` | `OPEN_NOW` value of the`SearchFilter` enum | -| `@private` | `@private` directive definition | -| `@private(scope:)` | `scope` argument on the `@private` directive definition | -| `Address` | `Address` interface | -| `Address.city` | `city` field on the `Address` interface | -| `ReviewInput` | `ReviewInput` input object type | -| `ReviewInput.author` | `author` input field on the `ReviewInput` input object type | -| `Entity` | `Entity` union definition | -| `DateTime` | Custom `DateTime` scalar type | -| `String` | Built-in `String` scalar type | - -Schema Coordinates are always unique. Each type, field, argument, enum value, or -directive may be referenced by exactly one possible Schema Coordinate. -For example, the following is *not* a valid Schema Coordinate: - -```graphql counter-example -Entity.Business +directive @private(scope: String!) on FIELD ``` - -In this counter example, `Entity.Business` is redundant since `Business` already -uniquely identifies the Business type. Such redundancy is disallowed by this -spec - every type, field, field argument, enum value, directive, and directive -argument has exactly one canonical Schema Coordinate. From 87a38e2addb7bda9b5c93ee3a1c0dbd2f53a3dd3 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Thu, 15 Apr 2021 10:17:01 -0700 Subject: [PATCH 12/26] standalone https://brians.wsu.edu/2016/05/31/standalone-stand-alone/ Co-authored-by: Benjie Gillam --- spec/Appendix B -- Grammar Summary.md | 2 +- spec/Section 2 -- Language.md | 2 +- spec/Section 3 -- Type System.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/Appendix B -- Grammar Summary.md b/spec/Appendix B -- Grammar Summary.md index e42bd7953..6d4688536 100644 --- a/spec/Appendix B -- Grammar Summary.md +++ b/spec/Appendix B -- Grammar Summary.md @@ -43,7 +43,7 @@ Token :: - FloatValue - StringValue -Punctuator :: one of ! $ & ( ) ... : = @ [ ] { | } +Punctuator :: one of ! $ & ( ) ... : = @ [ ] { | } . [lookahead != .] Name :: diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 76b5fadcb..d981abbe1 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -176,7 +176,7 @@ and is {Ignored}. ### Punctuators -Punctuator :: one of ! $ & ( ) ... : = @ [ ] { | } +Punctuator :: one of ! $ & ( ) ... : = @ [ ] { | } . [lookahead != .] GraphQL documents include punctuation in order to describe structure. GraphQL is a data description language and not a programming language, therefore GraphQL diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 8e2b5e08e..41b377513 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2189,7 +2189,7 @@ For example, `String` and `@deprecated(reason:)` are both valid schema coordinates which refer to built-in schema elements. Note: A {SchemaCoordinate} is not a definition within a GraphQL {Document}, but -a separate stand-alone grammar, intended to be used by tools to reference types, +a separate standalone grammar, intended to be used by tools to reference types, fields, and other *schema element*s. For example as references within documentation, or as lookup keys in usage frequency tracking. From 75c48ba25f4a665ec390829bcbd4c861dd063ce9 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Thu, 15 Apr 2021 23:07:26 -0700 Subject: [PATCH 13/26] update numbers --- spec/Section 3 -- Type System.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 41b377513..2cb1bc3d2 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2234,8 +2234,8 @@ SchemaCoordinate : @ Name ( Name : ) 1. Let {directiveName} be the value of the first {Name}. 2. Let {directive} be the directive in the {schema} named {directiveName}. 3. Assert {directive} must exist. - 7. Let {argumentName} be the value of the second {Name}. - 8. Return the argument of {directive} named {argumentName}. + 4. Let {argumentName} be the value of the second {Name}. + 5. Return the argument of {directive} named {argumentName}. **Examples** From 148d073afa7de9a0e766f6f1cd9fb87e8e43cd9f Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Thu, 15 Apr 2021 23:22:43 -0700 Subject: [PATCH 14/26] clarify element --- spec/Section 3 -- Type System.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 2cb1bc3d2..016ab6f4c 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2179,7 +2179,7 @@ SchemaCoordinate : *schema element* within a GraphQL Schema. :: A *schema element* is a specific instance of a named type, type field, -input field, enum value, field argument, directive, or directive argument. +input field, enum value, argument, or directive. A *schema coordinate* is always unique. Each *schema element* may be referenced by exactly one possible schema coordinate. From c43f4aacabc51ec18b5053546c5d2101157fcc0a Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Fri, 16 Apr 2021 00:13:03 -0700 Subject: [PATCH 15/26] Update Punctuator grammar --- spec/Appendix B -- Grammar Summary.md | 2 +- spec/Section 2 -- Language.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/Appendix B -- Grammar Summary.md b/spec/Appendix B -- Grammar Summary.md index 6d4688536..f9372bb9e 100644 --- a/spec/Appendix B -- Grammar Summary.md +++ b/spec/Appendix B -- Grammar Summary.md @@ -43,7 +43,7 @@ Token :: - FloatValue - StringValue -Punctuator :: one of ! $ & ( ) ... : = @ [ ] { | } . [lookahead != .] +Punctuator :: one of ! $ & ( ) ... : = @ [ ] { | } . [lookahead != {`.`, Digit}] Name :: diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index d981abbe1..d64237e0d 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -176,7 +176,7 @@ and is {Ignored}. ### Punctuators -Punctuator :: one of ! $ & ( ) ... : = @ [ ] { | } . [lookahead != .] +Punctuator :: one of ! $ & ( ) ... : = @ [ ] { | } . [lookahead != {`.`, Digit}] GraphQL documents include punctuation in order to describe structure. GraphQL is a data description language and not a programming language, therefore GraphQL From bb896cf2fbc01e80266db158985fa0cb7a291d46 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Fri, 16 Apr 2021 00:36:55 -0700 Subject: [PATCH 16/26] specify schema element --- spec/Section 3 -- Type System.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 016ab6f4c..2cb1bc3d2 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2179,7 +2179,7 @@ SchemaCoordinate : *schema element* within a GraphQL Schema. :: A *schema element* is a specific instance of a named type, type field, -input field, enum value, argument, or directive. +input field, enum value, field argument, directive, or directive argument. A *schema coordinate* is always unique. Each *schema element* may be referenced by exactly one possible schema coordinate. From e5a20921765755ba76069f9cfd19cbf016cd94ab Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Fri, 16 Apr 2021 01:43:32 -0700 Subject: [PATCH 17/26] fix example --- spec/Section 3 -- Type System.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 2cb1bc3d2..32730cbc2 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2274,5 +2274,5 @@ type Business { email: String @private(scope: "loggedIn") } -directive @private(scope: String!) on FIELD +directive @private(scope: String!) on FIELD_DEFINITION ``` From b65eb313af7a844d243473743881412cad049014 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Fri, 16 Apr 2021 01:57:34 -0700 Subject: [PATCH 18/26] clarify metafields --- spec/Section 3 -- Type System.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 32730cbc2..d70efe1db 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2186,7 +2186,9 @@ by exactly one possible schema coordinate. A *schema coordinate* may refer to either a defined or built-in *schema element*. For example, `String` and `@deprecated(reason:)` are both valid schema -coordinates which refer to built-in schema elements. +coordinates which refer to built-in schema elements. However it must not refer +to a meta-field. For example, `Business.__typename` is *not* a valid +schema coordinate. Note: A {SchemaCoordinate} is not a definition within a GraphQL {Document}, but a separate standalone grammar, intended to be used by tools to reference types, From c16a28bc544d3892246b4fadbce0ee9382dc2e33 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Fri, 16 Apr 2021 09:29:35 -0700 Subject: [PATCH 19/26] Better Punctator --- spec/Appendix B -- Grammar Summary.md | 8 +++++++- spec/Section 2 -- Language.md | 15 ++++++++++++++- 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/spec/Appendix B -- Grammar Summary.md b/spec/Appendix B -- Grammar Summary.md index f9372bb9e..549991391 100644 --- a/spec/Appendix B -- Grammar Summary.md +++ b/spec/Appendix B -- Grammar Summary.md @@ -43,7 +43,13 @@ Token :: - FloatValue - StringValue -Punctuator :: one of ! $ & ( ) ... : = @ [ ] { | } . [lookahead != {`.`, Digit}] +Punctuator :: + - DotPunctuator + - OtherPunctuator + +DotPunctuator :: `.` [lookahead != {`.`, Digit}] + +OtherPunctuator :: one of ! $ & ( ) ... : = @ [ ] { | } Name :: diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index d64237e0d..9646c867b 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -176,12 +176,25 @@ and is {Ignored}. ### Punctuators -Punctuator :: one of ! $ & ( ) ... : = @ [ ] { | } . [lookahead != {`.`, Digit}] +Punctuator :: + +- DotPunctuator +- OtherPunctuator + +DotPunctuator :: `.` [lookahead != {`.`, Digit}] + +OtherPunctuator :: one of ! $ & ( ) ... : = @ [ ] { | } GraphQL documents include punctuation in order to describe structure. GraphQL is a data description language and not a programming language, therefore GraphQL lacks the punctuation often used to describe mathematical expressions. +The {`.`} punctuator must not be followed by a {`.`} or {Digit}. This +ensures that the source {"..."} can only be interpreted as a single {`...`} and +not three {`.`}. It also avoids any potential ambiguity with {FloatValue}. As +an example the source {".123"} has no valid lexical representation (without this +restriction it would have been interpreted as {`.`} followed by {IntValue}). + ### Names Name :: From 93bd2c6c6a86c2a9744eb7f8748655de4f3b9b41 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Thu, 22 Apr 2021 00:05:20 -0700 Subject: [PATCH 20/26] Minor algo variable name refinements --- spec/Section 3 -- Type System.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index d70efe1db..be4f4bddb 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2178,8 +2178,8 @@ SchemaCoordinate : :: A *schema coordinate* is a human readable string that uniquely identifies a *schema element* within a GraphQL Schema. -:: A *schema element* is a specific instance of a named type, type field, -input field, enum value, field argument, directive, or directive argument. +:: A *schema element* is a specific instance of a named type, field, input +field, enum value, field argument, directive, or directive argument. A *schema coordinate* is always unique. Each *schema element* may be referenced by exactly one possible schema coordinate. @@ -2225,8 +2225,8 @@ SchemaCoordinate : Name . Name ( Name : ) 4. Let {fieldName} be the value of the second {Name}. 5. Let {field} be the field of {type} named {fieldName}. 6. Assert {field} must exist. - 7. Let {argumentName} be the value of the third {Name}. - 8. Return the argument of {field} named {argumentName}. + 7. Let {fieldArgumentName} be the value of the third {Name}. + 8. Return the argument of {field} named {fieldArgumentName}. SchemaCoordinate : @ Name 1. Let {directiveName} be the value of the first {Name}. @@ -2236,15 +2236,15 @@ SchemaCoordinate : @ Name ( Name : ) 1. Let {directiveName} be the value of the first {Name}. 2. Let {directive} be the directive in the {schema} named {directiveName}. 3. Assert {directive} must exist. - 4. Let {argumentName} be the value of the second {Name}. - 5. Return the argument of {directive} named {argumentName}. + 4. Let {directiveArgumentName} be the value of the second {Name}. + 5. Return the argument of {directive} named {directiveArgumentName}. **Examples** | Element Kind | *Schema Coordinate* | *Schema Element* | | ------------------ | -------------------------------- | ----------------------------------------------------------------------- | | Named Type | `Business` | `Business` type | -| Type Field | `Business.name` | `name` field on the `Business` type | +| Field | `Business.name` | `name` field on the `Business` type | | Input Field | `SearchCriteria.filter` | `filter` input field on the `SearchCriteria` input object type | | Enum Value | `SearchFilter.OPEN_NOW` | `OPEN_NOW` value of the `SearchFilter` enum | | Field Argument | `Query.searchBusiness(criteria:)`| `criteria` argument on the `searchBusiness` field on the `Query` type | From b2e42e88dce5073cdc955f465f27ba62a0c2c342 Mon Sep 17 00:00:00 2001 From: Mark Larah Date: Tue, 10 Dec 2024 11:17:02 -0600 Subject: [PATCH 21/26] whitespace fix --- spec/Appendix B -- Grammar Summary.md | 4 ++-- spec/Section 3 -- Type System.md | 1 - 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/spec/Appendix B -- Grammar Summary.md b/spec/Appendix B -- Grammar Summary.md index 549991391..d0777aac5 100644 --- a/spec/Appendix B -- Grammar Summary.md +++ b/spec/Appendix B -- Grammar Summary.md @@ -44,8 +44,8 @@ Token :: - StringValue Punctuator :: - - DotPunctuator - - OtherPunctuator +- DotPunctuator +- OtherPunctuator DotPunctuator :: `.` [lookahead != {`.`, Digit}] diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index be4f4bddb..07085ddb3 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -282,7 +282,6 @@ Schema extensions have the potential to be invalid if incorrectly defined. 2. Any non-repeatable directives provided must not already apply to the original Schema. - ## Types TypeDefinition : From 4ce2d48933e304799a84063b13317b3afd2b16a3 Mon Sep 17 00:00:00 2001 From: Mark Larah Date: Tue, 10 Dec 2024 11:37:20 -0600 Subject: [PATCH 22/26] add note about union members --- spec/Section 3 -- Type System.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 07085ddb3..89d7a80a6 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2181,7 +2181,7 @@ SchemaCoordinate : field, enum value, field argument, directive, or directive argument. A *schema coordinate* is always unique. Each *schema element* may be referenced -by exactly one possible schema coordinate. +by exactly one possible schema coordinate. There is a bidirectional 1:1 mapping. A *schema coordinate* may refer to either a defined or built-in *schema element*. For example, `String` and `@deprecated(reason:)` are both valid schema @@ -2189,10 +2189,16 @@ coordinates which refer to built-in schema elements. However it must not refer to a meta-field. For example, `Business.__typename` is *not* a valid schema coordinate. +Note: Unions members are not valid schema coordinates since they are references +to existing types in the schema. This preserves the 1:1 mapping property of +schema coordinates as stated above. + Note: A {SchemaCoordinate} is not a definition within a GraphQL {Document}, but a separate standalone grammar, intended to be used by tools to reference types, -fields, and other *schema element*s. For example as references within -documentation, or as lookup keys in usage frequency tracking. +fields, and other *schema element*s. Examples include: as references within +documentation to refer to types and fields in a schema, a lookup key that can +be used in logging tools to track how often particular fields are queried in +production. **Semantics** From 2d60b336531c1c98c5c31f96051711499b2bec3d Mon Sep 17 00:00:00 2001 From: Mark Larah Date: Tue, 10 Dec 2024 11:40:13 -0600 Subject: [PATCH 23/26] prettier --- spec/Appendix B -- Grammar Summary.md | 2 + spec/Section 2 -- Language.md | 8 +- spec/Section 3 -- Type System.md | 120 ++++++++++++++------------ 3 files changed, 69 insertions(+), 61 deletions(-) diff --git a/spec/Appendix B -- Grammar Summary.md b/spec/Appendix B -- Grammar Summary.md index d0777aac5..22dab575e 100644 --- a/spec/Appendix B -- Grammar Summary.md +++ b/spec/Appendix B -- Grammar Summary.md @@ -44,6 +44,7 @@ Token :: - StringValue Punctuator :: + - DotPunctuator - OtherPunctuator @@ -420,6 +421,7 @@ TypeSystemDirectiveLocation : one of - `INPUT_FIELD_DEFINITION` SchemaCoordinate : + - Name - Name . Name - Name . Name ( Name : ) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 9646c867b..3c22f0e71 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -189,10 +189,10 @@ GraphQL documents include punctuation in order to describe structure. GraphQL is a data description language and not a programming language, therefore GraphQL lacks the punctuation often used to describe mathematical expressions. -The {`.`} punctuator must not be followed by a {`.`} or {Digit}. This -ensures that the source {"..."} can only be interpreted as a single {`...`} and -not three {`.`}. It also avoids any potential ambiguity with {FloatValue}. As -an example the source {".123"} has no valid lexical representation (without this +The {`.`} punctuator must not be followed by a {`.`} or {Digit}. This ensures +that the source {"..."} can only be interpreted as a single {`...`} and not +three {`.`}. It also avoids any potential ambiguity with {FloatValue}. As an +example the source {".123"} has no valid lexical representation (without this restriction it would have been interpreted as {`.`} followed by {IntValue}). ### Names diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 89d7a80a6..ce75b331e 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2168,26 +2168,27 @@ scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122") ## Schema Coordinates SchemaCoordinate : - - Name - - Name . Name - - Name . Name ( Name : ) - - @ Name - - @ Name ( Name : ) -:: A *schema coordinate* is a human readable string that uniquely identifies a -*schema element* within a GraphQL Schema. +- Name +- Name . Name +- Name . Name ( Name : ) +- @ Name +- @ Name ( Name : ) -:: A *schema element* is a specific instance of a named type, field, input +:: A _schema coordinate_ is a human readable string that uniquely identifies a +_schema element_ within a GraphQL Schema. + +:: A _schema element_ is a specific instance of a named type, field, input field, enum value, field argument, directive, or directive argument. -A *schema coordinate* is always unique. Each *schema element* may be referenced +A _schema coordinate_ is always unique. Each _schema element_ may be referenced by exactly one possible schema coordinate. There is a bidirectional 1:1 mapping. -A *schema coordinate* may refer to either a defined or built-in *schema element*. -For example, `String` and `@deprecated(reason:)` are both valid schema +A _schema coordinate_ may refer to either a defined or built-in _schema +element_. For example, `String` and `@deprecated(reason:)` are both valid schema coordinates which refer to built-in schema elements. However it must not refer -to a meta-field. For example, `Business.__typename` is *not* a valid -schema coordinate. +to a meta-field. For example, `Business.__typename` is _not_ a valid schema +coordinate. Note: Unions members are not valid schema coordinates since they are references to existing types in the schema. This preserves the 1:1 mapping property of @@ -2196,68 +2197,73 @@ schema coordinates as stated above. Note: A {SchemaCoordinate} is not a definition within a GraphQL {Document}, but a separate standalone grammar, intended to be used by tools to reference types, fields, and other *schema element*s. Examples include: as references within -documentation to refer to types and fields in a schema, a lookup key that can -be used in logging tools to track how often particular fields are queried in +documentation to refer to types and fields in a schema, a lookup key that can be +used in logging tools to track how often particular fields are queried in production. **Semantics** -To refer to a *schema element*, a *schema coordinate* must be interpreted in the +To refer to a _schema element_, a _schema coordinate_ must be interpreted in the context of a GraphQL {schema}. SchemaCoordinate : Name - 1. Let {typeName} be the value of the first {Name}. - 2. Return the type in the {schema} named {typeName}. + +1. Let {typeName} be the value of the first {Name}. +2. Return the type in the {schema} named {typeName}. SchemaCoordinate : Name . Name - 1. Let {typeName} be the value of the first {Name}. - 2. Let {type} be the type in the {schema} named {typeName}. - 3. If {type} is an Enum type: - 1. Let {enumValueName} be the value of the second {Name}. - 2. Return the enum value of {type} named {enumValueName}. - 4. Otherwise if {type} is an Input Object type: - 1. Let {inputFieldName} be the value of the second {Name}. - 2. Return the input field of {type} named {inputFieldName}. - 5. Otherwise: - 1. Assert {type} must be an Object or Interface type. - 2. Let {fieldName} be the value of the second {Name}. - 3. Return the field of {type} named {fieldName}. + +1. Let {typeName} be the value of the first {Name}. +2. Let {type} be the type in the {schema} named {typeName}. +3. If {type} is an Enum type: +4. Let {enumValueName} be the value of the second {Name}. +5. Return the enum value of {type} named {enumValueName}. +6. Otherwise if {type} is an Input Object type: +7. Let {inputFieldName} be the value of the second {Name}. +8. Return the input field of {type} named {inputFieldName}. +9. Otherwise: +10. Assert {type} must be an Object or Interface type. +11. Let {fieldName} be the value of the second {Name}. +12. Return the field of {type} named {fieldName}. SchemaCoordinate : Name . Name ( Name : ) - 1. Let {typeName} be the value of the first {Name}. - 2. Let {type} be the type in the {schema} named {typeName}. - 3. Assert {type} must be an Object or Interface type. - 4. Let {fieldName} be the value of the second {Name}. - 5. Let {field} be the field of {type} named {fieldName}. - 6. Assert {field} must exist. - 7. Let {fieldArgumentName} be the value of the third {Name}. - 8. Return the argument of {field} named {fieldArgumentName}. + +1. Let {typeName} be the value of the first {Name}. +2. Let {type} be the type in the {schema} named {typeName}. +3. Assert {type} must be an Object or Interface type. +4. Let {fieldName} be the value of the second {Name}. +5. Let {field} be the field of {type} named {fieldName}. +6. Assert {field} must exist. +7. Let {fieldArgumentName} be the value of the third {Name}. +8. Return the argument of {field} named {fieldArgumentName}. SchemaCoordinate : @ Name - 1. Let {directiveName} be the value of the first {Name}. - 2. Return the directive in the {schema} named {directiveName}. + +1. Let {directiveName} be the value of the first {Name}. +2. Return the directive in the {schema} named {directiveName}. SchemaCoordinate : @ Name ( Name : ) - 1. Let {directiveName} be the value of the first {Name}. - 2. Let {directive} be the directive in the {schema} named {directiveName}. - 3. Assert {directive} must exist. - 4. Let {directiveArgumentName} be the value of the second {Name}. - 5. Return the argument of {directive} named {directiveArgumentName}. + +1. Let {directiveName} be the value of the first {Name}. +2. Let {directive} be the directive in the {schema} named {directiveName}. +3. Assert {directive} must exist. +4. Let {directiveArgumentName} be the value of the second {Name}. +5. Return the argument of {directive} named {directiveArgumentName}. **Examples** -| Element Kind | *Schema Coordinate* | *Schema Element* | -| ------------------ | -------------------------------- | ----------------------------------------------------------------------- | -| Named Type | `Business` | `Business` type | -| Field | `Business.name` | `name` field on the `Business` type | -| Input Field | `SearchCriteria.filter` | `filter` input field on the `SearchCriteria` input object type | -| Enum Value | `SearchFilter.OPEN_NOW` | `OPEN_NOW` value of the `SearchFilter` enum | -| Field Argument | `Query.searchBusiness(criteria:)`| `criteria` argument on the `searchBusiness` field on the `Query` type | -| Directive | `@private` | `@private` directive | -| Directive Argument | `@private(scope:)` | `scope` argument on the `@private` directive | - -The table above shows an example of a *schema coordinate* for every kind of -*schema element* based on the schema below. +| Element Kind | _Schema Coordinate_ | _Schema Element_ | +| ------------------ | --------------------------------- | --------------------------------------------------------------------- | +| Named Type | `Business` | `Business` type | +| Field | `Business.name` | `name` field on the `Business` type | +| Input Field | `SearchCriteria.filter` | `filter` input field on the `SearchCriteria` input object type | +| Enum Value | `SearchFilter.OPEN_NOW` | `OPEN_NOW` value of the `SearchFilter` enum | +| Field Argument | `Query.searchBusiness(criteria:)` | `criteria` argument on the `searchBusiness` field on the `Query` type | +| Directive | `@private` | `@private` directive | +| Directive Argument | `@private(scope:)` | `scope` argument on the `@private` directive | + +The table above shows an example of a _schema coordinate_ for every kind of +_schema element_ based on the schema below. ```graphql type Query { From d61cdc3153d94912a6b2e11c643f9b24667965b1 Mon Sep 17 00:00:00 2001 From: Mark Larah Date: Tue, 10 Dec 2024 11:49:01 -0600 Subject: [PATCH 24/26] formatting --- spec/Section 3 -- Type System.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index ce75b331e..ef1eeea43 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2182,7 +2182,7 @@ _schema element_ within a GraphQL Schema. field, enum value, field argument, directive, or directive argument. A _schema coordinate_ is always unique. Each _schema element_ may be referenced -by exactly one possible schema coordinate. There is a bidirectional 1:1 mapping. +by exactly one possible schema coordinate. A _schema coordinate_ may refer to either a defined or built-in _schema element_. For example, `String` and `@deprecated(reason:)` are both valid schema @@ -2190,9 +2190,9 @@ coordinates which refer to built-in schema elements. However it must not refer to a meta-field. For example, `Business.__typename` is _not_ a valid schema coordinate. -Note: Unions members are not valid schema coordinates since they are references -to existing types in the schema. This preserves the 1:1 mapping property of -schema coordinates as stated above. +Note: A union member is not a valid _schema coordinate_ as they reference +existing types in the schema. This preserves the uniqueness property of a +_schema coordinate_ as stated above. Note: A {SchemaCoordinate} is not a definition within a GraphQL {Document}, but a separate standalone grammar, intended to be used by tools to reference types, From caed065f874559a9bb87bc38c7365605fcd4682c Mon Sep 17 00:00:00 2001 From: Mark Larah Date: Thu, 2 Jan 2025 09:51:45 -0600 Subject: [PATCH 25/26] Update spec/Section 3 -- Type System.md Co-authored-by: Martin Bonnin --- spec/Section 3 -- Type System.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index ef1eeea43..25f63467a 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2178,8 +2178,8 @@ SchemaCoordinate : :: A _schema coordinate_ is a human readable string that uniquely identifies a _schema element_ within a GraphQL Schema. -:: A _schema element_ is a specific instance of a named type, field, input -field, enum value, field argument, directive, or directive argument. +:: A _schema element_ can be a named type, a field, an input +a field, an enum value, a field argument, a directive, or a directive argument. A _schema coordinate_ is always unique. Each _schema element_ may be referenced by exactly one possible schema coordinate. From 07b3bbdac29f23445be4084431d9aff7bebbf57b Mon Sep 17 00:00:00 2001 From: Mark Larah Date: Thu, 2 Jan 2025 10:14:20 -0600 Subject: [PATCH 26/26] Update spec/Section 3 -- Type System.md Co-authored-by: Martin Bonnin --- spec/Section 3 -- Type System.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 25f63467a..9f2476e6c 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2178,8 +2178,8 @@ SchemaCoordinate : :: A _schema coordinate_ is a human readable string that uniquely identifies a _schema element_ within a GraphQL Schema. -:: A _schema element_ can be a named type, a field, an input -a field, an enum value, a field argument, a directive, or a directive argument. +:: A _schema element_ can be a named type, a field, an input +field, an enum value, a field argument, a directive, or a directive argument. A _schema coordinate_ is always unique. Each _schema element_ may be referenced by exactly one possible schema coordinate.