From 1cbad5dff8b222aa381aec219604d4411752d75d Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Thu, 5 Jun 2025 13:45:25 +0100 Subject: [PATCH] Use `::` syntax for enum values --- spec/Appendix B -- Grammar Summary.md | 12 +++++-- spec/Section 2 -- Language.md | 8 ++++- spec/Section 3 -- Type System.md | 48 ++++++++++++++++++--------- 3 files changed, 49 insertions(+), 19 deletions(-) diff --git a/spec/Appendix B -- Grammar Summary.md b/spec/Appendix B -- Grammar Summary.md index 945e60751..22687c6bc 100644 --- a/spec/Appendix B -- Grammar Summary.md +++ b/spec/Appendix B -- Grammar Summary.md @@ -45,12 +45,15 @@ Token :: Punctuator :: +- ColonPunctuator - DotPunctuator - OtherPunctuator +ColonPunctuator :: `:` [lookahead != {`:`}] + DotPunctuator :: `.` [lookahead != {`.`, Digit}] -OtherPunctuator :: one of ! $ & ( ) ... : = @ [ ] { | } +OtherPunctuator :: one of ! $ & ( ) ... :: = @ [ ] { | } Name :: @@ -423,17 +426,20 @@ TypeSystemDirectiveLocation : one of SchemaCoordinate : - TypeCoordinate -- MemberCoordinate +- FieldCoordinate - ArgumentCoordinate +- ValueCoordinate - DirectiveCoordinate - DirectiveArgumentCoordinate TypeCoordinate : Name -MemberCoordinate : Name . Name +FieldCoordinate : Name . Name ArgumentCoordinate : Name . Name ( Name : ) +ValueCoordinate : Name :: Name + DirectiveCoordinate : @ Name DirectiveArgumentCoordinate : @ Name ( Name : ) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 81316f0cc..9d209602c 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -178,17 +178,23 @@ and is {Ignored}. Punctuator :: +- ColonPunctuator - DotPunctuator - OtherPunctuator +ColonPunctuator :: `:` [lookahead != {`:`}] + DotPunctuator :: `.` [lookahead != {`.`, Digit}] -OtherPunctuator :: one of ! $ & ( ) ... : = @ [ ] { | } +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 {`:`}. This ensures that the +source {"::"} can only be interpreted as a single {`::`} and not two {`:`}. + 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 diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 26e9a2dc8..e36b5d929 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2174,17 +2174,20 @@ scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122") SchemaCoordinate : - TypeCoordinate -- MemberCoordinate +- FieldCoordinate - ArgumentCoordinate +- ValueCoordinate - DirectiveCoordinate - DirectiveArgumentCoordinate TypeCoordinate : Name -MemberCoordinate : Name . Name +FieldCoordinate : Name . Name ArgumentCoordinate : Name . Name ( Name : ) +ValueCoordinate : Name :: Name + DirectiveCoordinate : @ Name DirectiveArgumentCoordinate : @ Name ( Name : ) @@ -2195,6 +2198,16 @@ _schema element_ within a GraphQL Schema. :: 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. +:: The _containing element_ of a _schema element_ is the schema element with one +fewer {Name} token that syntactically contains it. For example: + +- The containing element of an {ArgumentCoordinate} or + {DirectiveArgumentCoordinate} is the corresponding {FieldCoordinate} or + {DirectiveCoordinate} respectively. +- The containing element of a {FieldCoordinate} or {ValueCoordinate} is its + containing {TypeCoordinate}. +- {TypeCoordinate} and {DirectiveCoordinate} have no containing element. + A _schema coordinate_ is always unique. Each _schema element_ can be referenced by exactly one possible schema coordinate. @@ -2220,9 +2233,9 @@ production. To refer to a _schema element_, a _schema coordinate_ must be interpreted in the context of a GraphQL {schema}. -If the _schema element_ cannot be found, the resolve function will not yield a -value (without raising an error). However, an error will be raised if any -non-leaf nodes within a _schema coordinate_ cannot be found in the {schema}. +If the _schema element_ cannot be found, and either it has no _containing +element_ or its _containing element_ exists and is of the expected type, the +resolve function returns {null}. Otherwise, an error is raised. TypeCoordinate : Name @@ -2230,21 +2243,17 @@ TypeCoordinate : Name 2. Return the type in the {schema} named {typeName}, or {null} if no such type exists. -MemberCoordinate : Name . Name +FieldCoordinate : 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 exist, and must be an Enum, Input Object, Object or - Interface type. -4. 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}, or {null} if no - such value exists. -5. Otherwise, if {type} is an Input Object type: +3. Assert: {type} must exist, and must be an Input Object, Object or Interface + type. +4. 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}, or {null} if no such input field exists. -6. Otherwise: +5. Otherwise: 1. Let {fieldName} be the value of the second {Name}. 2. Return the field of {type} named {fieldName}, or {null} if no such field exists. @@ -2261,6 +2270,15 @@ ArgumentCoordinate : Name . Name ( Name : ) 8. Return the argument of {field} named {fieldArgumentName}, or {null} if no such argument exists. +ValueCoordinate : 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 exist, and must be an Enum type. +4. Let {enumValueName} be the value of the second {Name}. +5. Return the enum value of {type} named {enumValueName}, or {null} if no such + value exists. + DirectiveCoordinate : @ Name 1. Let {directiveName} be the value of {Name}. @@ -2283,8 +2301,8 @@ DirectiveArgumentCoordinate : @ Name ( Name : ) | 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 | +| Enum Value | `SearchFilter::OPEN_NOW` | `OPEN_NOW` value of the `SearchFilter` enum | | Directive | `@private` | `@private` directive | | Directive Argument | `@private(scope:)` | `scope` argument on the `@private` directive |