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
egoodwinx wants to merge 4 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
4 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
8275f38
Merge branch 'main' into field-extension
egoodwinx Dec 4, 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

@martinbonnin martinbonnin Oct 9, 2025

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

@BoD BoD Oct 9, 2025

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

Copy link
Member

@benjie benjie Dec 4, 2025

Choose a reason for hiding this comment

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

I'd be happy extending extend type to allow a prefixed description. The rule would be if it already has a description it would be invalid, just like adding the same interface twice.

Option 1:

"Description"
extend type MyType

Option 2:

extend type "Description" MyType

To me, the former is preferred over the latter, even though both are suboptimal.

There's also option 3:

extend "Description" type MyType

Or, and this may be the best option, option 4:

describe type MyType "Description"
describe field MyType.field "Description"
describe argument MyType.field(arg:) "Description"
describe enum MyEnum "Description"
describe enumValue MyEnum.VALUE "Description"
describe directive @foo "Description"
describe argument @foo(arg:) "Description"

Would mean the description is separate from the rest of the extension, but I think this is fine.

Thanks for highlighting this @BoD


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
Copy link
Member

@benjie benjie Dec 4, 2025

Choose a reason for hiding this comment

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

Suggested change
previously defined field. For example this may be a GraphQL service which is
previously defined field. For example this may be used by 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”)
Copy link
Member

@benjie benjie Dec 4, 2025

Choose a reason for hiding this comment

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

Beware of typographic quotes!

Suggested change
extend field User.name @deprecated(”Some reason”)
extend field User.name @deprecated(reason: "Some reason")

```

** Field Validation **
Copy link
Member

@benjie benjie Dec 4, 2025

Choose a reason for hiding this comment

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

The "Type" here relates to "type" as in "type-system" rather than type as in "object type".

Suggested change
** Field Validation **
**Type Validation**


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

@benjie benjie Dec 4, 2025

Choose a reason for hiding this comment

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

Suggested change
Field validation have the potential to be invalid if incorrectly defined.
Fields 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