docs: add naming and design guide#2279
Conversation
|
@sarahxsanders is attempting to deploy a commit to the The GraphQL Foundation Team on Vercel. A member of the Team first needs to authorize it. |
martinbonnin
left a comment
martinbonnin
left a comment
There was a problem hiding this comment.
Lots of very important things in that page!
I'd suggest breaking it down in different pages so those important topics get each their own entry points:
- naming, descriptions & linting
- nullability
- error handling
- scalars
- pagination
- anti-patterns
There was a problem hiding this comment.
I know this is the current recommendation but nullable fields are also a massive pain for client developers. With all the work going on about onError: "NULL" and @semanticNonNull, I wouldn't necessarily repeat that recommendation in 2026.
Can we leave this out until we have onError in the spec?
There was a problem hiding this comment.
Nit: maybe add directives? (camelCase if I'm not mistaken?, like @include, @semanticNonNull, etc...)
There was a problem hiding this comment.
Let's also recommend adding type descriptions?
There was a problem hiding this comment.
Thank you for being explicit about what null represents.
There was a problem hiding this comment.
Might also be worth mentioning https://scalars.graphql.org/
There was a problem hiding this comment.
There are looots of things to say on error handling, see also #2208
Might be worth extracting to a separate page?
There was a problem hiding this comment.
maybe worth collaborating and getting both efforts merged?
There was a problem hiding this comment.
Agreed. Also a reason I'd prefer a separate page. We can merge parts of this PR now and collaborate on the errors page.
There was a problem hiding this comment.
I have seen a recommendation somewhere (but can't remember where) to add the Connection.nodes as a shortcut and I like it. Curious to hear what you think
4 participants
Description
adds a new guide for the "schema governance" series on graphql.org/learn Includes new guide: Establish naming conventions and design standards:
Note: this needs heavy technical review - the content is based on heavy research i did, but since there's no strict naming conventions/guidance defined in the schema we will want to proceed with confidence that everything here is guidance we want to put out there!