Schema Coordinates #3044

leebyron · 2021-04-16T09:33:20Z

Depends on #3115

Adds:

DOT punctuator in lexer
Improvements to lexer errors around misuse of .
Minor improvement to parser core which simplified this addition
SchemaCoordinate node and isSchemaCoodinate() predicate
Support in print() and visit()
Added function parseSchemaCoordinate() since it is a parser entry point.
Added function resolveSchemaCoordinate() and resolveASTSchemeCoordinate() which implement the semantics (name mirrored from buildASTSchema) as well as the return type GraphQLSchemaElement

src/language/lexer.js

magicmark

Amazing!

This is way beyond what I was hacking with. Hadn't even considered reusing the existing parser. (I was fiddling around with regexes...)

Thanks for putting this together - this makes a lot of sense.

src/language/printer.js

src/language/ast.js

src/utilities/resolveSchemaCoordinate.js

leebyron · 2021-04-22T07:28:36Z

Great feedback - I think I've resolved both:

Replaced fieldName with memberName in the AST to ensure it's generalized between fields, input fields, and enum values. Those are all specific instances of the general pattern of "members of a set", which is pretty common terminology for this generalized dot access pattern.
Took both of your great suggestions for wrapping the return type of resolveSchemaCoordinate - the ResolvedSchemaElement type is now a union of wrappers. This had the added benefits of disambiguating between "field argument" and "directive argument" and including the coordinate context in the return value

src/language/ast.ts

Implements graphql/graphql-spec#794 Adds: * DOT punctuator in lexer * Improvements to lexer errors around misuse of `.` * Minor improvement to parser core which simplified this addition * `SchemaCoordinate` node and `isSchemaCoodinate()` predicate * Support in `print()` and `visit()` * Added function `parseSchemaCoordinate()` since it is a parser entry point. * Added function `resolveSchemaCoordinate()` and `resolveASTSchemaCoordinate()` which implement the semantics (name mirrored from `buildASTSchema`) as well as the return type `ResolvedSchemaElement`

Update comments per graphql/graphql-spec@5ac68a0

benjie

I think this is essentially good to go except for the comments noted, and that I think we should explicitly forbid {Ignored} from schema coordinates.

src/language/__tests__/parser-test.ts

src/language/__tests__/printer-test.ts

src/utilities/__tests__/resolveSchemaCoordinate-test.ts

src/utilities/resolveSchemaCoordinate.ts

benjie

Excellent work everyone, especially @magicmark!

@leebyron

[graphql#3049 rebased on main](graphql#3049). This is the last rebased PR from the original PR stack concluding with graphql#3049. * Rebased: graphql#3809 [Original: graphql#3092] * Rebased: graphql#3810 [Original: graphql#3074] * Rebased: graphql#3811 [Original: graphql#3077] * Rebased: graphql#3812 [Original: graphql#3065] * Rebased: graphql#3813 [Original: graphql#3086] * Rebased: graphql#3814 (this PR) [Original: graphql#3049] Update: graphql#3044 and graphql#3145 have been separated from this stack. Changes from original PR: 1. `astFromValue()` is deprecated instead of being removed. @leebyron comments from graphql#3049, the original PR: > Implements [graphql/graphql-spec#793](graphql/graphql-spec#793) > > * BREAKING: Changes default values from being represented as an assumed-coerced "internal input value" to a pre-coerced "external input value" (See chart below). > This allows programmatically provided default values to be represented in the same domain as values sent to the service via variable values, and allows it to have well defined methods for both transforming into a printed GraphQL literal string for introspection / schema printing (via `valueToLiteral()`) or coercing into an "internal input value" for use at runtime (via `coerceInputValue()`) > To support this change in value type, this PR adds two related behavioral changes: > > * Adds coercion of default values from external to internal at runtime (within `coerceInputValue()`) > * Removes `astFromValue()`, replacing it with `valueToLiteral()` for use in introspection and schema printing. `astFromValue()` performed unsafe "uncoercion" to convert an "Internal input value" directly to a "GraphQL Literal AST", where `valueToLiteral()` performs a well defined transform from "External input value" to "GraphQL Literal AST". > * Adds validation of default values during schema validation. > Since assumed-coerced "internal" values may not pass "external" validation (for example, Enum values), an additional validation error has been included which attempts to detect this case and report a strategy for resolution. > > Here's a broad overview of the intended end state: > > ![GraphQL Value Flow](https://user-images.githubusercontent.com/50130/118379946-51ac5300-b593-11eb-839f-c483ecfbc875.png) --------- Co-authored-by: Lee Byron <[email protected]>

…QLEnumValue (graphql#4288) this extracts logic from graphql#3044 and graphql#3145 (later rebased as graphql#3807 and [the full schema coordinate RFC](graphql/graphql-spec#794) This is a BREAKING CHANGE because these schema elements are now longer plain objects and function differently in various scenarios, for example with `String(<schemaElement>` `JSON.stringifu(<schemaElement>` and `.toString()` and `.toJSON()` --------- Co-authored-by: Jovi De Croock <[email protected]>

@leebyron

[graphql#3049 rebased on main](graphql#3049). This is the last rebased PR from the original PR stack concluding with graphql#3049. * Rebased: graphql#3809 [Original: graphql#3092] * Rebased: graphql#3810 [Original: graphql#3074] * Rebased: graphql#3811 [Original: graphql#3077] * Rebased: graphql#3812 [Original: graphql#3065] * Rebased: graphql#3813 [Original: graphql#3086] * Rebased: graphql#3814 (this PR) [Original: graphql#3049] Update: graphql#3044 and graphql#3145 have been separated from this stack. Changes from original PR: 1. `astFromValue()` is deprecated instead of being removed. @leebyron comments from graphql#3049, the original PR: > Implements [graphql/graphql-spec#793](graphql/graphql-spec#793) > > * BREAKING: Changes default values from being represented as an assumed-coerced "internal input value" to a pre-coerced "external input value" (See chart below). > This allows programmatically provided default values to be represented in the same domain as values sent to the service via variable values, and allows it to have well defined methods for both transforming into a printed GraphQL literal string for introspection / schema printing (via `valueToLiteral()`) or coercing into an "internal input value" for use at runtime (via `coerceInputValue()`) > To support this change in value type, this PR adds two related behavioral changes: > > * Adds coercion of default values from external to internal at runtime (within `coerceInputValue()`) > * Removes `astFromValue()`, replacing it with `valueToLiteral()` for use in introspection and schema printing. `astFromValue()` performed unsafe "uncoercion" to convert an "Internal input value" directly to a "GraphQL Literal AST", where `valueToLiteral()` performs a well defined transform from "External input value" to "GraphQL Literal AST". > * Adds validation of default values during schema validation. > Since assumed-coerced "internal" values may not pass "external" validation (for example, Enum values), an additional validation error has been included which attempts to detect this case and report a strategy for resolution. > > Here's a broad overview of the intended end state: > > ![GraphQL Value Flow](https://user-images.githubusercontent.com/50130/118379946-51ac5300-b593-11eb-839f-c483ecfbc875.png) --------- Co-authored-by: Lee Byron <[email protected]>

…QLEnumValue (graphql#4288) this extracts logic from graphql#3044 and graphql#3145 (later rebased as graphql#3807 and [the full schema coordinate RFC](graphql/graphql-spec#794) This is a BREAKING CHANGE because these schema elements are now longer plain objects and function differently in various scenarios, for example with `String(<schemaElement>` `JSON.stringifu(<schemaElement>` and `.toString()` and `.toJSON()` --------- Co-authored-by: Jovi De Croock <[email protected]>

@leebyron

[graphql#3049 rebased on main](graphql#3049). This is the last rebased PR from the original PR stack concluding with graphql#3049. * Rebased: graphql#3809 [Original: graphql#3092] * Rebased: graphql#3810 [Original: graphql#3074] * Rebased: graphql#3811 [Original: graphql#3077] * Rebased: graphql#3812 [Original: graphql#3065] * Rebased: graphql#3813 [Original: graphql#3086] * Rebased: graphql#3814 (this PR) [Original: graphql#3049] Update: graphql#3044 and graphql#3145 have been separated from this stack. Changes from original PR: 1. `astFromValue()` is deprecated instead of being removed. @leebyron comments from graphql#3049, the original PR: > Implements [graphql/graphql-spec#793](graphql/graphql-spec#793) > > * BREAKING: Changes default values from being represented as an assumed-coerced "internal input value" to a pre-coerced "external input value" (See chart below). > This allows programmatically provided default values to be represented in the same domain as values sent to the service via variable values, and allows it to have well defined methods for both transforming into a printed GraphQL literal string for introspection / schema printing (via `valueToLiteral()`) or coercing into an "internal input value" for use at runtime (via `coerceInputValue()`) > To support this change in value type, this PR adds two related behavioral changes: > > * Adds coercion of default values from external to internal at runtime (within `coerceInputValue()`) > * Removes `astFromValue()`, replacing it with `valueToLiteral()` for use in introspection and schema printing. `astFromValue()` performed unsafe "uncoercion" to convert an "Internal input value" directly to a "GraphQL Literal AST", where `valueToLiteral()` performs a well defined transform from "External input value" to "GraphQL Literal AST". > * Adds validation of default values during schema validation. > Since assumed-coerced "internal" values may not pass "external" validation (for example, Enum values), an additional validation error has been included which attempts to detect this case and report a strategy for resolution. > > Here's a broad overview of the intended end state: > > ![GraphQL Value Flow](https://user-images.githubusercontent.com/50130/118379946-51ac5300-b593-11eb-839f-c483ecfbc875.png) --------- Co-authored-by: Lee Byron <[email protected]>

…QLEnumValue (graphql#4288) this extracts logic from graphql#3044 and graphql#3145 (later rebased as graphql#3807 and [the full schema coordinate RFC](graphql/graphql-spec#794) This is a BREAKING CHANGE because these schema elements are now longer plain objects and function differently in various scenarios, for example with `String(<schemaElement>` `JSON.stringifu(<schemaElement>` and `.toString()` and `.toJSON()` --------- Co-authored-by: Jovi De Croock <[email protected]>

@leebyron

[graphql#3049 rebased on main](graphql#3049). This is the last rebased PR from the original PR stack concluding with graphql#3049. * Rebased: graphql#3809 [Original: graphql#3092] * Rebased: graphql#3810 [Original: graphql#3074] * Rebased: graphql#3811 [Original: graphql#3077] * Rebased: graphql#3812 [Original: graphql#3065] * Rebased: graphql#3813 [Original: graphql#3086] * Rebased: graphql#3814 (this PR) [Original: graphql#3049] Update: graphql#3044 and graphql#3145 have been separated from this stack. Changes from original PR: 1. `astFromValue()` is deprecated instead of being removed. @leebyron comments from graphql#3049, the original PR: > Implements [graphql/graphql-spec#793](graphql/graphql-spec#793) > > * BREAKING: Changes default values from being represented as an assumed-coerced "internal input value" to a pre-coerced "external input value" (See chart below). > This allows programmatically provided default values to be represented in the same domain as values sent to the service via variable values, and allows it to have well defined methods for both transforming into a printed GraphQL literal string for introspection / schema printing (via `valueToLiteral()`) or coercing into an "internal input value" for use at runtime (via `coerceInputValue()`) > To support this change in value type, this PR adds two related behavioral changes: > > * Adds coercion of default values from external to internal at runtime (within `coerceInputValue()`) > * Removes `astFromValue()`, replacing it with `valueToLiteral()` for use in introspection and schema printing. `astFromValue()` performed unsafe "uncoercion" to convert an "Internal input value" directly to a "GraphQL Literal AST", where `valueToLiteral()` performs a well defined transform from "External input value" to "GraphQL Literal AST". > * Adds validation of default values during schema validation. > Since assumed-coerced "internal" values may not pass "external" validation (for example, Enum values), an additional validation error has been included which attempts to detect this case and report a strategy for resolution. > > Here's a broad overview of the intended end state: > > ![GraphQL Value Flow](https://user-images.githubusercontent.com/50130/118379946-51ac5300-b593-11eb-839f-c483ecfbc875.png) --------- Co-authored-by: Lee Byron <[email protected]>

…QLEnumValue (graphql#4288) this extracts logic from graphql#3044 and graphql#3145 (later rebased as graphql#3807 and [the full schema coordinate RFC](graphql/graphql-spec#794) This is a BREAKING CHANGE because these schema elements are now longer plain objects and function differently in various scenarios, for example with `String(<schemaElement>` `JSON.stringifu(<schemaElement>` and `.toString()` and `.toJSON()` --------- Co-authored-by: Jovi De Croock <[email protected]>

The original schema coordinates PR on v17 (graphql#3044), since backported to 16.x.x, had non-specified support for schema coordinates for metafields. Co-authored-by: Benjie Gillam <[email protected]> Co-authored-by: Mark Larah <[email protected]> Co-authored-by: Yaacov Rydzinski <[email protected]>

@leebyron

[graphql#3049 rebased on main](graphql#3049). This is the last rebased PR from the original PR stack concluding with graphql#3049. * Rebased: graphql#3809 [Original: graphql#3092] * Rebased: graphql#3810 [Original: graphql#3074] * Rebased: graphql#3811 [Original: graphql#3077] * Rebased: graphql#3812 [Original: graphql#3065] * Rebased: graphql#3813 [Original: graphql#3086] * Rebased: graphql#3814 (this PR) [Original: graphql#3049] Update: graphql#3044 and graphql#3145 have been separated from this stack. Changes from original PR: 1. `astFromValue()` is deprecated instead of being removed. @leebyron comments from graphql#3049, the original PR: > Implements [graphql/graphql-spec#793](graphql/graphql-spec#793) > > * BREAKING: Changes default values from being represented as an assumed-coerced "internal input value" to a pre-coerced "external input value" (See chart below). > This allows programmatically provided default values to be represented in the same domain as values sent to the service via variable values, and allows it to have well defined methods for both transforming into a printed GraphQL literal string for introspection / schema printing (via `valueToLiteral()`) or coercing into an "internal input value" for use at runtime (via `coerceInputValue()`) > To support this change in value type, this PR adds two related behavioral changes: > > * Adds coercion of default values from external to internal at runtime (within `coerceInputValue()`) > * Removes `astFromValue()`, replacing it with `valueToLiteral()` for use in introspection and schema printing. `astFromValue()` performed unsafe "uncoercion" to convert an "Internal input value" directly to a "GraphQL Literal AST", where `valueToLiteral()` performs a well defined transform from "External input value" to "GraphQL Literal AST". > * Adds validation of default values during schema validation. > Since assumed-coerced "internal" values may not pass "external" validation (for example, Enum values), an additional validation error has been included which attempts to detect this case and report a strategy for resolution. > > Here's a broad overview of the intended end state: > > ![GraphQL Value Flow](https://user-images.githubusercontent.com/50130/118379946-51ac5300-b593-11eb-839f-c483ecfbc875.png) --------- Co-authored-by: Lee Byron <[email protected]>

…QLEnumValue (graphql#4288) this extracts logic from graphql#3044 and graphql#3145 (later rebased as graphql#3807 and [the full schema coordinate RFC](graphql/graphql-spec#794) This is a BREAKING CHANGE because these schema elements are now longer plain objects and function differently in various scenarios, for example with `String(<schemaElement>` `JSON.stringifu(<schemaElement>` and `.toString()` and `.toJSON()` --------- Co-authored-by: Jovi De Croock <[email protected]>

The original schema coordinates PR on v17 (graphql#3044), since backported to 16.x.x, had non-specified support for schema coordinates for metafields. Co-authored-by: Benjie Gillam <[email protected]> Co-authored-by: Mark Larah <[email protected]> Co-authored-by: Yaacov Rydzinski <[email protected]>

@leebyron

[graphql#3049 rebased on main](graphql#3049). This is the last rebased PR from the original PR stack concluding with graphql#3049. * Rebased: graphql#3809 [Original: graphql#3092] * Rebased: graphql#3810 [Original: graphql#3074] * Rebased: graphql#3811 [Original: graphql#3077] * Rebased: graphql#3812 [Original: graphql#3065] * Rebased: graphql#3813 [Original: graphql#3086] * Rebased: graphql#3814 (this PR) [Original: graphql#3049] Update: graphql#3044 and graphql#3145 have been separated from this stack. Changes from original PR: 1. `astFromValue()` is deprecated instead of being removed. @leebyron comments from graphql#3049, the original PR: > Implements [graphql/graphql-spec#793](graphql/graphql-spec#793) > > * BREAKING: Changes default values from being represented as an assumed-coerced "internal input value" to a pre-coerced "external input value" (See chart below). > This allows programmatically provided default values to be represented in the same domain as values sent to the service via variable values, and allows it to have well defined methods for both transforming into a printed GraphQL literal string for introspection / schema printing (via `valueToLiteral()`) or coercing into an "internal input value" for use at runtime (via `coerceInputValue()`) > To support this change in value type, this PR adds two related behavioral changes: > > * Adds coercion of default values from external to internal at runtime (within `coerceInputValue()`) > * Removes `astFromValue()`, replacing it with `valueToLiteral()` for use in introspection and schema printing. `astFromValue()` performed unsafe "uncoercion" to convert an "Internal input value" directly to a "GraphQL Literal AST", where `valueToLiteral()` performs a well defined transform from "External input value" to "GraphQL Literal AST". > * Adds validation of default values during schema validation. > Since assumed-coerced "internal" values may not pass "external" validation (for example, Enum values), an additional validation error has been included which attempts to detect this case and report a strategy for resolution. > > Here's a broad overview of the intended end state: > > ![GraphQL Value Flow](https://user-images.githubusercontent.com/50130/118379946-51ac5300-b593-11eb-839f-c483ecfbc875.png) --------- Co-authored-by: Lee Byron <[email protected]>

…QLEnumValue (graphql#4288) this extracts logic from graphql#3044 and graphql#3145 (later rebased as graphql#3807 and [the full schema coordinate RFC](graphql/graphql-spec#794) This is a BREAKING CHANGE because these schema elements are now longer plain objects and function differently in various scenarios, for example with `String(<schemaElement>` `JSON.stringifu(<schemaElement>` and `.toString()` and `.toJSON()` --------- Co-authored-by: Jovi De Croock <[email protected]>

The original schema coordinates PR on v17 (graphql#3044), since backported to 16.x.x, had non-specified support for schema coordinates for metafields. Co-authored-by: Benjie Gillam <[email protected]> Co-authored-by: Mark Larah <[email protected]> Co-authored-by: Yaacov Rydzinski <[email protected]>

leebyron requested a review from IvanGoncharov April 16, 2021 09:33

leebyron force-pushed the schema-coordinates branch 2 times, most recently from c7b87e2 to 0a5630a Compare April 16, 2021 09:46

IvanGoncharov added the spec RFC Implementation of a proposed change to the GraphQL specification label Apr 16, 2021

magicmark reviewed Apr 16, 2021

View reviewed changes

src/language/lexer.js Outdated Show resolved Hide resolved

magicmark approved these changes Apr 16, 2021

View reviewed changes

src/language/printer.js Outdated Show resolved Hide resolved

IvanGoncharov reviewed Apr 20, 2021

View reviewed changes

src/language/ast.js Outdated Show resolved Hide resolved

IvanGoncharov reviewed Apr 20, 2021

View reviewed changes

src/utilities/resolveSchemaCoordinate.js Outdated Show resolved Hide resolved

leebyron force-pushed the schema-coordinates branch from a4a8920 to 42f9072 Compare April 22, 2021 07:27

leebyron requested a review from IvanGoncharov April 22, 2021 16:58

leebyron force-pushed the schema-coordinates branch from 42f9072 to 1399f7c Compare May 27, 2021 23:55

leebyron changed the base branch from main to lexer-cleanup May 27, 2021 23:55

leebyron added the PR: feature 🚀 requires increase of "minor" version number label May 27, 2021

leebyron force-pushed the lexer-cleanup branch 2 times, most recently from 3451e3e to 2f893d6 Compare May 28, 2021 22:21

leebyron force-pushed the schema-coordinates branch from 1399f7c to 3cec8c2 Compare May 28, 2021 22:31

leebyron mentioned this pull request May 28, 2021

Add coordinate field to schema element definitions #3145

Open

leebyron force-pushed the schema-coordinates branch from 3cec8c2 to e688f88 Compare May 30, 2021 06:30

IvanGoncharov reviewed Jun 1, 2021

View reviewed changes

src/language/ast.ts Outdated Show resolved Hide resolved

leebyron force-pushed the schema-coordinates branch from e688f88 to c68ca9b Compare June 2, 2021 17:55

leebyron requested a review from IvanGoncharov June 2, 2021 17:55

leebyron mentioned this pull request Jun 2, 2021

[2021-01-07] Schema Coordinates: Add functions to graphql-js for schema coordinate parsing/printing graphql/graphql-wg#581

Closed

leebyron force-pushed the lexer-cleanup branch from 0d6a096 to b6864ac Compare June 3, 2021 16:51

leebyron force-pushed the schema-coordinates branch from c68ca9b to 8fa8a4c Compare June 3, 2021 17:00

Base automatically changed from lexer-cleanup to main June 3, 2021 17:34

leebyron force-pushed the schema-coordinates branch from 8fa8a4c to 98e7541 Compare June 3, 2021 17:53

martijnwalraven mentioned this pull request Jun 18, 2021

Alternative GraphQL schema abstraction apollographql/federation#823

Closed

yaacovCR mentioned this pull request Dec 29, 2022

RFC: Schema Coordinates #3807

Closed

magicmark and others added 2 commits July 1, 2025 14:57

schema coordinates spec wording edits (#4440)

42d1f4d

Update comments per graphql/graphql-spec@5ac68a0

Merge branch 'next' into schema-coordinates

b70005f

vercel bot deployed to Preview July 3, 2025 19:17 View deployment

benjie requested changes Jul 3, 2025

View reviewed changes

magicmark added 2 commits July 6, 2025 15:54

No {Ignored} tokens when parsing schema coordinates (#4450)

04dd13e

Schema coordinates (#4463)

fd6ce88

magicmark mentioned this pull request Aug 26, 2025

Add benjie's suggested changes to schema-coordinates #4478

Merged

Add benjie's suggested changes to schema-coordinates (#4478)

fe0ad30

benjie approved these changes Aug 27, 2025

View reviewed changes

Merge remote-tracking branch 'origin/next' into schema-coordinates

2775f81

vercel bot deployed to Preview September 1, 2025 05:08 View deployment

patch ci

81b8a23

leebyron merged commit ec9c063 into next Sep 1, 2025
29 checks passed

JoviDeCroock mentioned this pull request Oct 14, 2025

Backport schema coordinates #4493

Merged

Schema Coordinates #3044

Schema Coordinates #3044

Uh oh!

Conversation

leebyron commented Apr 16, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

magicmark left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

leebyron commented Apr 22, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

benjie left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

benjie left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

leebyron commented Apr 16, 2021 •

edited

Loading

leebyron commented Apr 22, 2021 •

edited

Loading