graphql / graphql/graphql.github.io

Add more GraphQL Schema Design Guidlines

Open
#2,353 0 comments 1 reaction 0 assignees View on GitHub
Dominant language
TypeScript
Stars
889
Forks
1.5k
Avg merge
4d 12h
Merged PRs (30d)
21

Description

We have a page for Schema Design https://graphql.org/learn/schema-design/

I think we should add lots more entries to this page!

There's lots of well-established principles and conventions already, see https://github.com/magicmark/awesome-graphql-schema-design

Not everything is universally applicable. We should seek to only upstream things that make sense to 99% of users, or add clarification statements for things that are less universally true but still largely true.

For any non-trivial additions, I would propose we review PRs either in the main wg or golden path wg (cc @benjie) meetings?

Let's create sub-issues for each topic.

_(This ticket is being made as an action item from Golden Path WG Mar 12th 2026)_

Contributor guide

Open the contributing guide

Research direction

Start with the existing Schema Design page at graphql.org/learn/schema-design/ and compare it with the referenced awesome-graphql-schema-design list. Break the broad request into topic-specific sub-issues, and treat each addition as done only after its scope and applicability are agreed and the relevant PR has been reviewed.

Written by the indexing model from the issue text.

Assessment

Tech stack
graphql
Domain
api, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.