Why this is hard to get right
Marcus is a backend engineer at a Series B logistics startup. His team just made the call to migrate their REST API to GraphQL to support three new clients: a customer-facing web portal, a driver mobile app, and a warehouse management system integration.
He opens ChatGPT and types: "Write a GraphQL schema for a logistics platform with shipments, drivers, and customers."
The output comes back in 45 seconds. It looks reasonable at first glance — Shipment, Driver, Customer types, a handful of queries, some mutations. Marcus copies it into his editor.
Then reality sets in.
The list queries use offset pagination. His team standardized on cursor-based pagination six months ago after hitting performance walls. Every field on Shipment is nullable, even required ones. There are no subscriptions, even though the mobile app needs real-time shipment status updates. The naming mixes camelCase and snake_case across fields. And there are no SDL comments, so the schema is useless as documentation without a full rewrite.
Marcus now spends two hours manually fixing the schema. He fixes the pagination pattern, adds nullability constraints, writes inline comments, and adds the subscription type. He's essentially writing the schema himself with the AI output as a rough reference — not a usable starting point.
This is the failure mode most developers hit. The AI wasn't wrong — it just didn't know what Marcus knew. It didn't know about the mobile client's real-time requirements. It didn't know the team's naming standards. It didn't know which fields were nullable by design and which were nullable by accident.
A prompt that captures this context before generation turns a 2-hour cleanup into a 10-minute review. That's the difference between a prompt that helps and a prompt that just moves the work around.
Common mistakes to avoid
Listing Entities Without Relationships
Naming types like 'users, products, orders' without specifying how they relate forces the AI to guess cardinality. Does one user have many orders? Do orders belong to organizations or users? Wrong assumptions here cascade into broken schema design.
Skipping Pagination Requirements
Not specifying cursor-based vs. offset pagination leads the AI to pick a default that may not match your infrastructure. Migrating pagination patterns after clients are built is a breaking API change — get it right in the prompt.
Omitting Client Consumer Context
A schema for a mobile client, a third-party REST bridge, and an internal admin tool requires different design tradeoffs. Without naming your consumers, the AI optimizes for a generic use case that fits none of them well.
Forgetting to Request SDL Comments
GraphQL schemas without inline documentation become tribal knowledge immediately. If you don't explicitly ask for SDL description strings on every type and field, the AI will omit them — and your docs tooling (GraphiQL, Rover) will produce empty docs.
Not Specifying Authorization Patterns
Asking for a schema without mentioning role-based access means the AI won't flag which fields need authorization guards. You discover these gaps in production when a query returns data it shouldn't.
The transformation
Write a GraphQL schema for my app. It has users, products, and orders. Include queries and mutations.
**Act as a senior GraphQL architect** with deep experience in production API design. **Domain context:** I'm building a B2B e-commerce platform. The primary consumers are a React web app and a React Native mobile app. A third-party ERP integration will also query orders read-only. **Design a GraphQL schema that includes:** 1. Types: `User`, `Organization`, `Product`, `Order`, `OrderLineItem` 2. Queries: fetch paginated products (cursor-based), fetch a single order by ID, list orders by organization with date range filtering 3. Mutations: `createOrder`, `updateOrderStatus`, `addProductToOrganization` 4. Subscriptions: `orderStatusChanged` **Constraints:** - Use relay-style connection patterns for all list queries - Follow camelCase naming for fields, PascalCase for types - Include inline SDL comments on every type and field - Flag any N+1 query risks with a `# DATALOADER REQUIRED` comment **Output format:** Valid SDL (Schema Definition Language) followed by a markdown documentation table summarizing each type, its fields, and access roles.
Why this works
Role Priming
Assigning the AI the role of 'senior GraphQL architect' activates patterns associated with production-grade decisions — like Relay connections, dataloader annotations, and nullability best practices — rather than tutorial-level defaults.
Consumer Specificity
Naming the exact clients consuming the API (React web, React Native, ERP read-only) gives the AI enough context to make the right design tradeoffs. Mobile clients need field efficiency; ERP integrations need stable read queries. These are different schemas.
Explicit Operations
Providing a numbered list of required queries, mutations, and subscriptions eliminates ambiguity. The AI generates exactly what you need rather than guessing what a 'typical' e-commerce schema includes.
Named Constraints
Specifying Relay-style connections, casing conventions, and annotation patterns gives the AI guardrails that match your team's existing standards. Without constraints, AI defaults to the most common patterns it saw during training.
Dual Output Format
Requesting both valid SDL and a markdown documentation table produces two immediately usable artifacts. The SDL goes into version control; the table goes into your internal developer docs — skipping a separate documentation step.
The framework behind the prompt
GraphQL schema design sits at the intersection of domain-driven design (DDD) and API contract theory. The schema is not just a technical artifact — it's a public contract between your API and every client that consumes it. Breaking changes in a schema carry the same weight as breaking changes in a public REST API.
The Schema-First Design pattern (as opposed to code-first) treats the SDL file as the single source of truth. Teams agree on the schema before writing resolvers, which allows frontend and backend teams to develop in parallel against a shared contract. This is the approach GraphQL's creators at Facebook intended, and it's where AI assistance delivers the most value — generating a complete, reviewed SDL early in the design process.
The Relay Connection Specification is the most widely adopted pagination standard in GraphQL. It uses cursor-based pagination through Connection, Edge, and PageInfo types, enabling stable pagination even as underlying data changes — a critical property for mobile clients.
From a performance standpoint, the N+1 problem is the most common production pitfall in GraphQL APIs. Without dataloader batching, a query for 100 orders with their associated users triggers 101 database queries. Naming this concern explicitly in a schema design prompt allows the AI to annotate the schema with implementation guidance before the problem is baked in.
Prompt variations
Act as a GraphQL architect specializing in multi-tenant SaaS applications.
Design a GraphQL schema for a project management SaaS platform. Tenants are Workspaces. Each workspace contains Projects, Tasks, and Members.
Include:
- All core CRUD mutations with input types
- Cursor-based paginated queries for tasks and projects
- A
mequery returning the authenticated user with their workspace memberships - Inline SDL comments on every type and field
- A
# TENANT_SCOPE_REQUIREDannotation on any resolver that must be scoped to the current workspace
Conventions: PascalCase types, camelCase fields, non-null fields marked explicitly.
Output: Valid SDL followed by a markdown table of mutation input types and their required vs. optional fields.
Act as a backend engineer building an internal admin GraphQL API.
The API serves a React-based internal dashboard used by the customer success and operations teams. It must NOT be exposed publicly.
Domain: Customer account management for a subscription SaaS. Types include Account, Subscription, Invoice, SupportTicket.
Design a schema that includes:
- Queries: search accounts by name/email, fetch subscription history, list open support tickets
- Mutations:
updateAccountTier,issueCreditToAccount,closeTicket - No subscriptions required
- Role annotations: mark mutations that require an
ADMINrole with a# REQUIRES_ROLE: ADMINcomment
Output: SDL with annotations, plus a short risk section in markdown noting any fields that carry PII or billing data.
Act as a developer advocate producing a public GraphQL API reference.
I'm publishing a read-only public GraphQL API for a real-time sports data platform. Consumers are third-party developers building fan-facing apps.
Types required: League, Team, Player, Match, MatchEvent
Design requirements:
- All queries only — no mutations or subscriptions in the public schema
- Rate-limit annotations using
# RATE_LIMITED: 60rpmon expensive queries - Deprecation notices using the
@deprecateddirective on any legacy fields - Full SDL description strings written for a developer audience unfamiliar with the domain
Output: SDL formatted for publication, followed by a "Getting Started" markdown section showing 3 example queries a developer would run first.
When to use this prompt
Backend Engineers Scaffolding New Services
Engineers starting a new microservice can generate a complete, annotated SDL file that follows team conventions, saving 2-3 hours of initial schema drafting and review cycles.
API Platform Teams Standardizing Docs
Platform teams responsible for internal developer experience can produce consistent schema documentation tables for every domain object, reducing onboarding time for new contributors.
Full-Stack Developers Prototyping Products
Solo developers building SaaS MVPs can rapidly produce a production-aligned schema with N+1 warnings and relay pagination baked in, skipping early performance debt.
Technical Leads Preparing Code Reviews
Tech leads can generate a reference schema to compare against a PR, making review comments more concrete and grounded in architectural best practices.
Developer Advocates Writing API Guides
Advocates creating documentation for public GraphQL APIs can use this prompt to generate both the SDL and the human-readable docs table in one pass.
Pro tips
- 1
Specify your pagination pattern upfront — Relay-style cursor connections and offset-based pagination produce very different schemas. Choosing the wrong one early creates breaking changes later.
- 2
Name your client consumers explicitly. A schema serving only an internal web app can be more permissive than one serving third-party integrations, and the AI will apply different design heuristics based on this.
- 3
Include at least one example of your existing naming convention so the AI matches it exactly. Consistency across schema files matters more than which convention you pick.
- 4
Ask for N+1 and authorization annotations as inline comments. These hints are invisible in the SDL output unless you explicitly request them, but they're critical for your resolver implementation phase.
The most important thing you can give the AI is a clear picture of your business domain — not just entity names, but how entities relate and what operations matter most to your users.
Use this structure in your prompt:
- Core entities and their cardinality — e.g., "One Organization has many Users. One User can belong to many Organizations. One Order belongs to exactly one Organization."
- Primary read patterns — What are the three most common queries your clients will run? Name them explicitly.
- Primary write patterns — Which mutations are on the critical path (order creation, status updates, etc.) vs. administrative actions?
- Access control boundaries — Which types or fields are restricted by role? Flag these upfront so the AI can annotate them.
- Performance-sensitive areas — Which queries touch large data sets or require aggregation? Ask the AI to flag these with dataloader or caching annotations.
When you structure your context this way, the AI doesn't just generate types and fields — it generates a schema that reflects how your system actually works.
A GraphQL schema doubles as API documentation when SDL description strings are done well. Here's how to get AI-generated documentation that your team will actually use:
Request three levels of documentation in your prompt:
- Type-level descriptions — One sentence explaining what business concept this type represents. Example:
"""Represents a single purchase order placed by an organization.""" - Field-level descriptions — One sentence per field explaining its meaning and any constraints. Example:
"""The ISO 4217 currency code for this order. Defaults to USD.""" - Argument-level descriptions — For query arguments, explain valid values and behavior. Example:
"""Filter orders created after this ISO 8601 timestamp."""
After generation, ask the AI to produce a companion markdown table with columns: Type, Field, Description, Nullable, Access Role. This table format works well in Confluence, Notion, or GitHub wikis and gives non-engineering stakeholders a readable API reference without needing GraphiQL.
If your organization runs multiple GraphQL services, your schema design prompt needs additional context about how services will federate or stitch together.
For Apollo Federation, add to your prompt:
- Which types are entity types (shared across services and resolved via
@keydirective) - Which fields are extended from another service
- Which service owns each type
Example addition to the after prompt:
This schema is a subgraph in an Apollo Federation setup.
- `User` is an entity type owned by the Auth service. Reference it with @key(fields: "id") but do not define its fields here.
- `Order` is owned by this service and should be defined in full.
- `Product` is a stub from the Catalog service — extend it with @key(fields: "id") and add only the `reorderQuantity` field.
Providing this level of context prevents the AI from generating monolithic schemas that break federation boundaries — a common and expensive mistake to fix after services are deployed.
When not to use this prompt
This prompt pattern isn't the right tool when you're iterating on an existing, deployed schema. Adding fields to a live production schema carries deprecation and versioning concerns that require a different prompt focused on backward compatibility analysis, not initial design.
It's also not ideal for generating resolver code — schema design and resolver implementation require different context and should be separate prompts.
Finally, if your team uses a code-first approach (generating SDL from TypeScript decorators or Python classes), skip the SDL output and instead prompt for the annotated type definitions in your framework of choice.
Troubleshooting
AI generates overly simplified types that don't reflect my actual domain
Add a 'domain constraints' section to your prompt listing 3-5 real business rules. For example: 'An Order can only transition from PENDING to CONFIRMED if all line items have available inventory.' Business rules force the AI to model the domain properly rather than defaulting to a tutorial-level CRUD schema.
Generated SDL has syntax errors or invalid directives
Add 'Validate that the SDL you generate is parseable by graphql-js 16.x' to your prompt constraints. Also ask the AI to double-check federation directives (@key, @external, @requires) if you're using Apollo Federation, since these are the most common source of AI-generated SDL syntax errors.
Schema doesn't include the pagination pattern I asked for
Be explicit with an example. Instead of 'use Relay-style connections,' include a short inline example: 'For example, the products query should return ProductConnection with edges: [ProductEdge] and pageInfo: PageInfo — matching the Relay Connection Specification exactly.' Examples outperform descriptions for structural requirements.
How to measure success
A well-generated GraphQL schema from this prompt should pass five checks:
- Parseable — the SDL loads without errors in graphql-js or your preferred validator
- Complete — all requested queries, mutations, and subscriptions are present with correct argument and return types
- Annotated — every type and field has an SDL description string
- Convention-compliant — naming follows the casing rules you specified, with no inconsistencies
- Risk-flagged — N+1 risks, authorization boundaries, and rate-sensitive queries are marked with inline comments
If the output passes all five, it's ready for team review. If it fails any, that failure point tells you exactly which constraint to reinforce in a follow-up prompt.
Now try it on something of your own
Reading about the framework is one thing. Watching it sharpen your own prompt is another — takes 90 seconds, no signup.
a production-ready GraphQL schema with documentation
Try one of these
Frequently asked questions
Yes — add a section to your prompt describing your existing REST endpoints and their response shapes. Ask the AI to map each REST resource to a GraphQL type, noting where REST patterns like nested IDs should become proper object relationships in the schema.
Paste 5-10 lines of an existing SDL file into your prompt as a 'convention reference' block. Tell the AI to match the naming, nullability, and description style exactly. This is more reliable than describing conventions in prose.
Break the schema into domain modules — authentication, billing, inventory, etc. Generate one module at a time, then ask the AI to produce a final stitching plan that shows how the modules connect through shared types and cross-module queries.
No — keep schema design and resolver implementation in separate prompts. Schema design is a structural exercise; resolver logic depends on your data layer, ORM, and caching strategy. Mixing them produces mediocre output for both.
Paste the output into the GraphQL Playground schema validator, run it through the Apollo Rover CLI, or use an online SDL linter. Always validate before sharing with your team — AI-generated SDL occasionally produces subtle syntax errors in complex union or interface definitions.