Skip to content

add initial outline for field extensions #1196

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
+31 −0
Draft

add initial outline for field extensions #1196

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
10cbf4b
add initial outline for field extensions
egoodwinx Oct 8, 2025
b14e553
address pr comments
egoodwinx Oct 9, 2025
20e079f
minor formatting changes
egoodwinx Oct 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion spec/Appendix C -- Grammar Summary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -318,6 +318,11 @@ FieldsDefinition : { FieldDefinition+ }
FieldDefinition : Description? Name ArgumentsDefinition? : Type
Directives[Const]?

FieldExtension :

- extend field MemberCoordinate Directives[const]?
- extend field description MemberCoordinate
Copy link
Contributor

@BoD BoD Oct 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was the intent to have the ability to add a description to fields? The other extensions don't allow that. What happens if the field already has a description? I suggest we only allow adding directives:

Suggested change
- extend field MemberCoordinate Directives[const]?
- extend field description MemberCoordinate
- extend field MemberCoordinate Directives[Const]

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was suggested by @benjie on Discord. I think it makes sense, especially in an AI age where descriptions give valuable info to LLMs. But true it needs validation rules.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the heads up 👍.

Interesting! Although I would find it a bit odd to allow adding descriptions on fields but not on types and more (maybe this should go to a different PR that does that more broadly and keep this one focused on directives).

If we do want to keep this I think the grammar should look like:

Suggested change
- extend field MemberCoordinate Directives[const]?
- extend field description MemberCoordinate
- extend field MemberCoordinate Directives[Const]
- extend field Description MemberCoordinate


ArgumentsDefinition : ( InputValueDefinition+ )

InputValueDefinition : Description? Name : Type DefaultValue? Directives[Const]?
Expand All @@ -328,7 +333,7 @@ InterfaceTypeDefinition :
FieldsDefinition
- Description? interface Name ImplementsInterfaces? Directives[Const]?
[lookahead != `{`]

InterfaceTypeExtension :

- extend interface Name ImplementsInterfaces? Directives[Const]?
Expand Down
25 changes: 25 additions & 0 deletions spec/Section 3 -- Type System.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1105,6 +1105,31 @@ Object type extensions have the potential to be invalid if incorrectly defined.
6. The resulting extended object type must be a super-set of all interfaces it
implements.

### Field Extensions

FieldExtension :

- extend field MemberCoordinate Directives[const]?
- extend field description MemberCoordinate

Field extensions are used to represent a field which has been extended from some
previously defined field. For example this may be a GraphQL service which is
itself an extension of another GraphQL service.

In this example, we can deprecate the id field on the User type.

```graphql example
extend field User.name @deprecated(”Some reason”)
```

** Field Validation **

Field validation have the potential to be invalid if incorrectly defined.

1. MemberCoordinate must be resolved to an existing field on a object or interface type.
2. Any non-repeatable directives provided must not already apply to the previous
field.

## Interfaces

InterfaceTypeDefinition :
Expand Down
Loading