Search the docs, videos, blog, apps, teams, skills and release notes.
At a glance
What it is
Guides expert-level graphql schema design implementation: api-design and design-patterns decision frameworks, production-ready patterns, and concrete templates for graphql schema design workflows.
A skill is a written procedure a bot loads when a job calls for it. This one is a single file, SKILL.md, and the whole file is on this page.
The whole file, exactly as it downloads. Read it before you rely on it.
SKILL.md
783 lines · 5,769 words
Use this skill when:
User is designing a new GraphQL API from scratch and needs schema structure guidance -- type definitions, query/mutation/subscription organization, and naming conventions
User is migrating a REST API to GraphQL and needs to understand how to translate resource-based endpoints into a graph-based type system
Guides expert-level graphql schema design implementation: api-design and design-patterns decision frameworks, production-ready patterns, and concrete templates for graphql schema design workflows.
Nothing. It ships with Murage, which is open source. Your bots run on the AI plan you already have.
Yes. Open it in Settings → Skills to read, edit or duplicate it. Skill Guard scans it again after every edit.
Download the app, connect the AI you already pay for, and tell your Chief of Staff what needs doing. Plan on about ten minutes from install to a working team.
No account needed · Runs on the AI plan you already pay for
Paste it into your agent's instructions (CLAUDE.md, AGENTS.md or a custom GPT), or add it to a bot in Murage.
Ask Ember for the bot, then switch the skill on in its settings.
Step 1
Send your Chief of Staff this message. It proposes the bot and its role first, and creates it when you say go.
Send this to Ember
“Create a bot that uses the GraphQL Schema Design skill, and show me the plan first.”
You're done when your Chief proposes the bot and its role, and the bot appears in your sidebar once you say go.
Step 2
You're done when you see the bot’s skills and the library.
Step 3
You're done when the skill shows as on for that bot.
Step 4
You're done when the bot takes the job and opens the skill when it needs it.
Prefer to do it yourself? Choose + in the sidebar, then New Bot.Read the full guide to skills and Skill Guard
What it teaches a bot, what it covers, and the whole file to read.
What it covers
When to Use
Process
Output Format
Rules
Edge Cases
Example
GraphQL Schema Design Review -- E-Commerce Platform
User needs to model complex domain relationships -- bidirectional associations, polymorphic types, recursive structures, or union/interface hierarchies
User is building a federated GraphQL architecture across multiple microservices and needs schema composition guidance
User asks how to version or evolve a GraphQL schema without breaking existing clients
User needs to design mutations with proper input types, error handling patterns, and optimistic UI support
User is designing a schema for pagination, filtering, and sorting at scale and needs a consistent, extensible pattern
Do NOT use this skill when:
User needs GraphQL resolver implementation guidance -- this skill covers schema structure, not resolver logic or DataLoader setup
User needs GraphQL authentication/authorization middleware configuration -- check the backend-security skills
User needs GraphQL client-side query writing or fragment composition -- this skill is server-schema design only
User is asking about REST API design without GraphQL involvement -- check API design skills in the sibling subcategory
User needs GraphQL subscription infrastructure setup (WebSocket servers, pub/sub brokers) -- that is an infrastructure concern beyond schema design
User needs GraphQL performance monitoring, APM tooling, or query complexity analysis at runtime -- check observability skills
User is asking about gRPC or OpenAPI/Swagger schema design -- separate skill domains
Before writing a single type definition, map the domain thoroughly.
List all core business entities and draw their relationships -- identify which are nodes in a graph (independent entities with identity) vs. value objects (embedded data without identity)
Distinguish ownership relationships (a Post belongs to exactly one User) from association relationships (a Post has many Tags that exist independently)
Catalog the top 10-15 read access patterns the UI actually needs -- screens, components, and dashboards drive schema shape more than the database schema does
Catalog write operations grouped by actor, frequency, and atomicity requirements -- a single checkout mutation may span inventory, payment, and order creation
Identify which entities are queried by ID most often vs. by collection with filtering -- entities queried by ID are candidates for the Node interface; filterable collections need pagination and filter input types
Note cardinality: one-to-one, one-to-many, and many-to-many relationships have distinct modeling strategies in GraphQL
Flag any data that is computed or derived (aggregates, calculated fields) -- these need special attention to avoid expensive resolver chains
Establish scalar, enum, interface, and union types before building object types.
Start with custom scalars for domain primitives: DateTime (ISO-8601 strings), URL, EmailAddress, UUID, JSON, Decimal (for currency/precise numbers) -- never use raw String for typed values the client will parse
Define enums for all closed sets of values: OrderStatus, UserRole, PaymentMethod -- use SCREAMING_SNAKE_CASE for enum values per GraphQL spec convention
Design interfaces for shared contracts across multiple types. The Node interface (id: ID!) is the single most important interface -- implement it on every top-level entity to enable generic caching and refetching in clients like Apollo and Relay
Use the Error interface pattern to create a structured error type hierarchy: define a base UserError interface with message: String! and code: String!, then create domain-specific error types implementing it
Define union types for truly polymorphic responses where types share no fields -- use SearchResult = User | Post | Product rather than a single SearchResult object with nullable fields
Create Connection and Edge types following the Relay Cursor Connections specification -- even if not using Relay, this pattern provides a battle-tested pagination contract: UserConnection, UserEdge, PageInfo
Establish XxxInput naming convention for all input types used in mutations -- never reuse output object types as mutation inputs because their field requirements differ
Structure the Query type to be discoverable, consistent, and client-friendly.
Use singular/plural naming rigorously: user(id: ID!): User for single-entity lookup, users(filter: UserFilterInput, pagination: PaginationInput): UserConnection! for collection queries
Never return nullable connections -- a collection query that finds zero results should return an empty connection, not null. Use UserConnection! not UserConnection
Group related fields semantically and document them with triple-quoted SDL descriptions -- these appear in GraphQL Playground, GraphiQL, and schema documentation tools
Implement the Node interface lookup at the root: node(id: ID!): Node enables clients to refetch any entity by global ID without knowing its type in advance
Avoid deeply nested required arguments -- a query like organizationUsersByRole(orgId: ID!, role: UserRole!, status: UserStatus) should use a single filter input type
Design filter input types to be additive: UserFilterInput { id: ID, email: String, role: UserRole, status: UserStatus, createdAfter: DateTime } -- all fields optional, combined with AND semantics by default
Add orderBy: [UserOrderByInput!] as a separate argument from filtering -- this keeps filtering and sorting concerns independent and allows multiple sort keys
Consider search vs. filter: full-text search (query: String) is a different pattern from structured filtering and should be a separate field or argument
Mutations require the most careful design because they represent state changes with side effects.
Follow the single-responsibility principle strictly: one mutation per logical operation. createUser, updateUser, deleteUser are separate mutations -- never a generic mutateUser operation
Use namespaced mutation naming for large schemas: userCreate, userUpdate, userDelete groups all user mutations alphabetically in tooling. Alternatively use the Mutation.user: UserMutations nested object pattern (note: this breaks introspection-based tooling in some clients -- document the tradeoff)
Every mutation takes exactly one input object argument: createUser(input: CreateUserInput!): CreateUserPayload! -- this is the most future-proof signature because new fields can be added to the input without changing the mutation signature
Every mutation returns a payload type, never a raw object type: CreateUserPayload { user: User, errors: [UserError!]! } -- the payload wrapper allows adding fields like clientMutationId (Relay), warnings, and side-effect data without a breaking change
Always include an errors field in the mutation payload -- use the union/interface error pattern so clients can distinguish between ValidationError, AuthorizationError, NotFoundError, and ConflictError with typed fields
Design optimistic UI support: ensure the returned payload contains all fields the UI needs to update local state without a separate refetch -- if creating a post, return the full Post type with resolved author, category, and tag data
Mark destructive mutations with a DeleteXxxPayload { deletedId: ID!, success: Boolean! } pattern -- returning the deleted ID enables cache eviction in Apollo Client and similar
Use upsert mutations sparingly and only when the create-vs-update distinction is genuinely irrelevant to the caller -- document the idempotency semantics explicitly
Graph relationships are the core value proposition of GraphQL -- design them carefully.
Default to returning full nested objects rather than foreign key IDs -- post { author { id name avatarUrl } } is the GraphQL idiom; returning authorId: ID! defeats the purpose and forces the client to make additional queries
For large one-to-many relationships (more than ~20 items), always paginate using cursor-based connections. Offset pagination (skip/limit) has correctness issues with real-time data and does not scale -- prefer opaque cursor strings
The Relay Cursor Connection spec fields: edges { node cursor } pageInfo { hasNextPage hasPreviousPage startCursor endCursor } -- implement all four pageInfo fields even if bidirectional pagination is not immediately needed
For many-to-many relationships with edge data (a User enrolled in a Course with an enrolledAt date and progress percentage), model the join as an explicit Enrollment type with its own connection
Avoid circular reference problems by designing which side "owns" the traversal -- User.posts is fine; adding Post.author.posts in a single query should be handled by query depth limiting in the server, not prevented in schema design
Use @deprecated(reason: "Use newFieldName instead") directive on old fields rather than removing them -- GraphQL's deprecation mechanism is the proper version evolution tool
For highly connected data (social graphs, org hierarchies), add depth and limit arguments to recursive fields: user { followers(depth: 2, limit: 100) { ... } } to prevent unbounded traversal
Consistent naming is not cosmetic -- it determines how discoverable and maintainable the schema is.
Types: PascalCase (UserProfile, OrderLineItem) -- never abbreviate unless the abbreviation is universal in the domain (SKU, URL, ID are fine; Usr and Ord are not)
Fields: camelCase (firstName, createdAt, isActive) -- Boolean fields should use is, has, or can prefix: isVerified, hasChildren, canEdit
Input types: [Verb][Noun]Input for mutations (CreateOrderInput, UpdateUserProfileInput), [Noun]FilterInput for queries (ProductFilterInput)
Payload types: [Verb][Noun]Payload (CreateOrderPayload, UpdateUserPayload)
Enum values: SCREAMING_SNAKE_CASE (PENDING_REVIEW, OUT_OF_STOCK)
Connection types: [Noun]Connection and [Noun]Edge (ProductConnection, ProductEdge)
Write SDL descriptions for every type, every field with non-obvious semantics, and every argument. Use the triple-quote format: """Returns the 10 most recent orders. Use the connection args for pagination beyond 10."""
Document nullability intent: if a field is nullable because it is genuinely optional vs. because it might fail to load vs. because it is computed async, note this in the description
Before finalizing, run the schema through a validation checklist.
Check for N+1 risk: any field that requires a database query per parent object is an N+1 risk. Identify these fields and ensure they are addressed in the resolver layer with DataLoader batching -- the schema design should not be changed to hide this, but the field should be documented
Verify all mutations have error payloads and all queries have non-nullable connection returns
Run the schema through a linter -- graphql-schema-linter enforces naming conventions, deprecation requirements, and description coverage automatically
Check query depth -- define a maximum allowed query depth (typically 7-10 levels) and verify no legitimate client query requires more than this
Simulate the top 5 client queries against the schema using a tool like graphql-inspector -- verify the field paths are intuitive and require no unnecessary traversal
Validate that no input type has required fields that should be optional, and no output type has non-null fields that could realistically be absent
Check for breaking changes before any schema deployment using graphql-inspector diff -- adding fields and types is non-breaking; removing fields, changing argument types, and changing nullability from nullable to non-null are all breaking
Schema design is not a one-time event -- establish the governance model upfront.
Commit to semantic versioning via schema changelog, not URL versioning (/graphql/v2) -- GraphQL evolves gracefully through deprecation and field addition
Establish a deprecation policy: deprecated fields must remain in the schema for a minimum of 30-90 days (set based on your release cadence and client deployment speed)
Use the @deprecated directive immediately when introducing a replacement: oldField: String @deprecated(reason: "Use newField which returns a typed object") -- never remove first, deprecate first
Set up graphql-inspector in CI to automatically block pull requests that introduce breaking changes to the public schema
Maintain a schema changelog (SCHEMA_CHANGELOG.md) alongside the code with entries for every added type, added field, deprecated field, and reason for deprecation
Consider schema contracts for large teams: use a schema registry (Apollo Schema Registry or open-source Hive) to track schema versions, validate composition in federated setups, and enforce review gates
## GraphQL Schema Design Review
### Domain Model Summary
- Core entities: [list with brief description]
- Key relationships: [entity → entity with cardinality]
- Primary access patterns: [top 5 queries driving design]
- Write operations: [top 5 mutations driving design]
### Schema Design Decisions
| Decision | Choice | Rationale | Trade-offs |
|----------|--------|-----------|------------|
| Pagination style | Cursor (Relay spec) / Offset | [reason] | [trade-off] |
| Error handling | Payload union / errors array | [reason] | [trade-off] |
| Nullability policy | Strict non-null / permissive | [reason] | [trade-off] |
| ID strategy | Global ID (Node) / local ID | [reason] | [trade-off] |
| Naming convention | Standard camelCase/PascalCase | [reason] | [trade-off] |
### Schema Structure
#### Custom Scalars
[List with justification for each non-standard scalar]
#### Interfaces
[List with the contract each interface enforces]
#### Type Definitions (SDL)
[Full SDL for all types, organized as:]
-- Scalars and Enums
-- Interfaces
-- Core object types (most important entities first)
-- Connection types
-- Input types (query filters, mutation inputs)
-- Payload types (mutation returns)
-- Query root
-- Mutation root
#### Relationship Map
[Diagram or table showing type → type traversal paths]
### Validation Results
| Check | Status | Notes |
|-------|--------|-------|
| Naming conventions | ✅ / ⚠️ / ❌ | [details] |
| All mutations have payload types | ✅ / ⚠️ / ❌ | [details] |
| All collections paginated | ✅ / ⚠️ / ❌ | [details] |
| N+1 risks documented | ✅ / ⚠️ / ❌ | [details] |
| Breaking change check | ✅ / ⚠️ / ❌ | [details] |
| Description coverage | ✅ / ⚠️ / ❌ | [details] |
### Evolution Notes
- Fields marked for deprecation: [list]
- Planned additions: [list]
- Breaking changes required (with migration plan): [list]NEVER remove a field without first deprecating it for at least 30 days. Field removal is a breaking change for all clients even if no client currently uses the field -- unknown clients, generated SDKs, and cached queries all depend on introspection stability. Use @deprecated(reason: "...") and remove only after confirming zero usage via query analytics.
NEVER change a field from nullable to non-null without treating it as a breaking change. Making a field non-null (String → String!) breaks any client that handles null values for that field. The reverse (non-null to nullable) is safe. When in doubt, start nullable and tighten later only after all clients are verified.
ALWAYS put the errors field on every mutation payload. A mutation that returns createUser: User! has no mechanism to communicate domain errors (email already taken, validation failure) without throwing GraphQL errors, which forces clients to parse error extensions. The errors: [UserError!]! field on a payload type is the correct pattern.
NEVER use generic types as mutation inputs. Reusing output types as input types (createUser(user: User)) breaks immediately when the output type adds computed fields, relations, or server-generated fields like id and createdAt. Always create dedicated CreateUserInput, UpdateUserInput types with exactly the fields the client should provide.
ALWAYS paginate collections that could exceed 20-30 items in production. A field returning [Post!]! with no pagination argument will eventually return thousands of objects, causing memory and latency problems on both server and client. The only exception is truly bounded collections (a user's 2FA recovery codes, a product's fixed set of images with a hard cap of 10).
NEVER design around a specific client's current data shape. Schema design based on "this is what the React component tree looks like today" creates a brittle, client-coupled schema that cannot serve mobile apps, partner integrations, or internal tooling. Design around the domain model; let clients compose what they need.
ALWAYS implement the Node interface on top-level entities. The node(id: ID!): Node root query with global IDs (base64-encoded TypeName:localId) is not just a Relay pattern -- it enables any client to efficiently refetch stale data, powers cache normalization in Apollo Client, and provides a universal entity lookup mechanism.
NEVER put business logic in the schema design itself. Schema defines structure and contracts, not computation rules. Avoid temptations like adding authorization flags directly as scalar fields (canUserEdit: Boolean! computed per-viewer) unless this is a deliberate, documented design choice -- these fields are expensive (one resolver call per object in a list) and couple the schema to viewer-specific state.
ALWAYS distinguish between null-because-absent and null-because-failed. A nullable field thumbnailUrl: String could mean "this product has no thumbnail" (intentional) or "the CDN URL resolver failed" (error). Use the @semanticNonNull pattern in documentation, or model the error case explicitly with a union type. Clients cannot distinguish these cases without schema-level clarity.
NEVER add a field to the schema until you have a resolver implementation plan. Underfetching is a client problem; an unresolvable field is a server contract violation. If a field is added to the schema but the resolver returns null due to unimplemented logic, clients build against a broken contract. Coordinate schema additions with resolver work, or gate new fields behind a feature flag in schema stitching.
When wrapping existing REST endpoints in a GraphQL schema, resist the urge to mirror the REST resource structure 1:1. REST resources are organized around CRUD operations on individual entities; GraphQL schemas should be organized around how clients actually traverse the data graph. A REST endpoint GET /users/{id}/orders?status=COMPLETED becomes user(id: ID!) { orders(filter: { status: COMPLETED }) { ... } } -- the nesting reflects ownership, not endpoint hierarchy. Use schema stitching or a thin gateway layer so the GraphQL schema can evolve independently of the underlying REST endpoints. Start with read-only query types wrapping existing GET endpoints, then introduce mutations only once the query layer is stable.
The choice between interface and union is often confused. Use an interface when the polymorphic types share a meaningful common contract that clients will query against -- SearchResult types that are all Node implementors with id and title fields should be an interface, because clients can write a fragment that applies to all of them. Use a union when the types are genuinely heterogeneous with no shared fields -- PaymentMethod = CreditCard | BankTransfer | CryptoCurrency should be a union because there is no meaningful shared contract. The practical test: if you find yourself adding shared fields to a union type, convert it to an interface. Inline fragments (... on CreditCard { cardNumber lastFour }) work identically on both.
In multi-tenant SaaS applications, some data is global (product catalog, public user profiles) and some is viewer-scoped (the current user's orders, their organization's settings). Avoid adding currentUser: User fields directly on other types (order { currentUserCanApprove: Boolean! }) because this couples the schema to the authenticated context and makes the schema unusable for batch processing, admin tools, or unauthenticated access. Instead, put viewer-specific capabilities on a dedicated viewer: Viewer root query type that contains the authenticated user's context. The Viewer type holds orders, permissions, organization -- all scoped to the authenticated session -- while global types remain free of viewer context.
In Apollo Federation or schema stitching architectures, each subgraph owns a slice of the overall schema. The key design rules are: every entity that is referenced across subgraph boundaries must implement @key with a stable, queryable field (almost always the primary id); subgraphs should extend types only to add fields they own the data for; and no subgraph should extend a type just to add computed fields that belong in the consuming application layer. The main failure mode in federated schemas is ownership ambiguity -- two teams both adding fields to the User type without coordination causes type conflicts at composition time. Establish a schema ownership registry (a simple table in a wiki is sufficient for teams under 20) that maps each type and field to an owning team.
Organizational hierarchies, category trees, comment threads, and file systems are common recursive structures. Do not model these with unbounded recursive types (Category { children: [Category!]! }). Instead, add depth control arguments (children(depth: Int = 1): [Category!]!) and document the maximum supported depth. For very deep or very large trees (org charts with 10,000 nodes), consider a flattened list representation at the schema level (organization { allDepartments: [Department!]! } with parentId on each Department) and let the client reconstruct the tree -- this approach is more efficient for large datasets and avoids the query complexity explosion of deeply nested traversals.
Subscriptions share the type system with queries and mutations, but their design requirements differ. A subscription payload should contain the minimum data needed to update the client's local state -- it should not be a full entity dump. Design subscription types to include the event type (UserUpdatedEvent { eventType: UserEventType!, user: User!, changedFields: [String!]! }), not just the current state. This allows clients to apply optimistic updates correctly and distinguish create/update/delete events. Never model a subscription to return a connection type -- subscriptions push individual events, not paginated collections. For filtered subscriptions (onOrderUpdated(orderId: ID!)), document the filter semantics precisely and limit the number of filterable dimensions to prevent server-side subscription fan-out.
When a schema grows beyond 50 types, tooling and process become as important as design patterns. Split the SDL across multiple files organized by domain (user, product, order, payment) and merge them at build time. Use graphql-schema-linter with a configuration file that enforces description coverage (at least 80% of public fields documented), naming conventions, and deprecation format. Establish a schema review process: every PR that adds or modifies schema definitions requires review by the schema owner (typically a platform or API team member) in addition to code review. Track field usage with GraphQL observability tools to identify candidates for deprecation -- fields with zero usage over 90 days should be deprecated proactively.
Input: "We're building an e-commerce platform with a team of 8 engineers. We have Products with variants (size/color), a Cart and Checkout flow, Orders with line items, and User accounts with addresses. We need to support both a web storefront and a mobile app as clients. What should our GraphQL schema look like?"
Output:
Core entities: User, Product, ProductVariant, Cart, CartItem, Order, OrderLineItem, Address, Category
Key relationships:
User → [Address] (one-to-many, user owns addresses)
User → [Order] (one-to-many, user owns orders)
User → Cart (one-to-one, user has one active cart)
Product → [ProductVariant] (one-to-many, bounded -- max ~50 variants per product)
Product → [Category] (many-to-many via ProductCategoryEdge)
Cart → [CartItem] (one-to-many, CartItem references ProductVariant)
Order → [OrderLineItem] (one-to-many, immutable snapshot of purchase)
Primary access patterns:
Product listing with filtering by category, price range, availability (paginated)
Product detail page with all variants, images, and descriptions
Cart retrieval with current prices and availability status
Order history for authenticated user (paginated, filterable by status)
Checkout flow: validate cart → create order → process payment
Write operations:
Add/update/remove cart items
Create order from cart (checkout)
Update user profile and addresses
Apply discount codes to cart
Cancel order (status transition)
| Decision | Choice | Rationale | Trade-offs |
|---|---|---|---|
| Pagination style | Cursor (Relay spec) | Product and order lists can be large; real-time inventory changes make offset pagination unreliable | Slightly more complex client code vs. offset |
| Error handling | Payload type with errors: [UserError!]! | Checkout and cart operations have rich domain errors (out of stock, invalid coupon) needing typed responses | Clients must check both errors and the entity field |
| Nullability policy | Strict non-null on reliable data; nullable on computed/external-dependent fields | Reduces client null-checking burden on core fields | Server must guarantee non-null fields -- requires careful resolver implementation |
| ID strategy | Global ID implementing Node interface | Both web and mobile clients use Apollo Client; global IDs enable cache normalization without configuration | Base64 encoding adds minor overhead; local IDs exposed via separate legacyId field for REST migration |
| Naming convention | Standard GraphQL conventions: camelCase fields, PascalCase types, SCREAMING_SNAKE_CASE enums | Consistent with client SDK generation tools and GraphQL community norms | No trade-off for new projects |
DateTime -- ISO-8601 timestamp strings (2024-03-15T10:30:00Z); used on all createdAt, updatedAt, expiresAt fields
Decimal -- Arbitrary-precision decimal as string ("19.99"); used for all monetary amounts to avoid floating-point errors
URL -- Validated URL string; used for imageUrl, thumbnailUrl fields
JSON -- Arbitrary JSON object; used for ProductVariant.attributes to handle the open-ended nature of variant attributes (size charts, material specs)
Node -- id: ID!; implemented by User, Product, ProductVariant, Cart, Order, Address, Category -- enables node(id: ID!) root lookup and Apollo Client cache normalization
UserError -- message: String!, code: String!; base for all domain errors returned in mutation payloads
# ─── Scalars ────────────────────────────────────────────────────────────
scalar DateTime
scalar Decimal
scalar URL
scalar JSON
# ─── Enums ──────────────────────────────────────────────────────────────
enum OrderStatus {
PENDING
PAYMENT_PROCESSING
CONFIRMED
SHIPPED
DELIVERED
CANCELLED
REFUNDED
}
enum CartItemStatus {
AVAILABLE
LOW_STOCK # fewer than 5 units remaining
OUT_OF_STOCK
PRICE_CHANGED # price changed since item was added
}
enum AddressType {
SHIPPING
BILLING
}
enum SortDirection {
ASC
DESC
}
enum ProductSortField {
PRICE
NAME
CREATED_AT
POPULARITY
}
# ─── Interfaces ──────────────────────────────────────────────────────────
interface Node {
id: ID!
}
interface UserError {
message: String!
code: String!
}
# ─── Error Types ─────────────────────────────────────────────────────────
type ValidationError implements UserError {
message: String!
code: String!
field: String! # which input field caused the error
}
type NotFoundError implements UserError {
message: String!
code: String!
entityType: String!
}
type OutOfStockError implements UserError {
message: String!
code: String!
productVariant: ProductVariant!
requestedQuantity: Int!
availableQuantity: Int!
}
type InvalidCouponError implements UserError {
message: String!
code: String!
couponCode: String!
}
# ─── Core Types ──────────────────────────────────────────────────────────
"""
A registered user account. Guests interact with Cart without a User.
"""
type User implements Node {
id: ID!
email: String!
firstName: String!
lastName: String!
"""Computed display name combining firstName and lastName."""
displayName: String!
isEmailVerified: Boolean!
createdAt: DateTime!
updatedAt: DateTime!
addresses(type: AddressType): [Address!]!
defaultShippingAddress: Address
orders(
filter: OrderFilterInput
first: Int
after: String
last: Int
before: String
): OrderConnection!
}
type Address implements Node {
id: ID!
type: AddressType!
firstName: String!
lastName: String!
line1: String!
line2: String
city: String!
stateOrProvince: String!
postalCode: String!
country: String! # ISO 3166-1 alpha-2
isDefault: Boolean!
}
"""
A product in the catalog. All purchasable items are ProductVariants;
Product holds shared content and metadata.
"""
type Product implements Node {
id: ID!
name: String!
slug: String!
description: String!
"""Short description for listing cards, max 160 characters."""
shortDescription: String!
thumbnailUrl: URL
imageUrls: [URL!]!
categories: [Category!]!
variants: [ProductVariant!]!
"""
Returns the lowest price across all available variants.
Null if all variants are out of stock.
"""
minPrice: Decimal
maxPrice: Decimal
isAvailable: Boolean!
createdAt: DateTime!
updatedAt: DateTime!
}
"""
A specific purchasable configuration of a Product (e.g., size=L, color=Red).
"""
type ProductVariant implements Node {
id: ID!
product: Product!
sku: String!
"""
Open-ended attribute map. Keys depend on product type:
e.g., {"size": "L", "color": "Red"} or {"material": "Cotton", "fit": "Slim"}.
"""
attributes: JSON!
"""Human-readable variant label, e.g., 'Large / Red'."""
label: String!
price: Decimal!
compareAtPrice: Decimal # original price for sale display
inventoryQuantity: Int!
isAvailable: Boolean!
imageUrl: URL
}
type Category implements Node {
id: ID!
name: String!
slug: String!
description: String
parentCategory: Category
"""Direct children only. Use depth argument for subtree traversal."""
childCategories(depth: Int = 1): [Category!]!
products(
filter: ProductFilterInput
orderBy: ProductOrderByInput
first: Int
after: String
): ProductConnection!
}
"""
The current user's shopping cart.
Anonymous carts are identified by a cartToken stored client-side.
"""
type Cart implements Node {
id: ID!
items: [CartItem!]!
subtotal: Decimal!
discountAmount: Decimal!
estimatedTax: Decimal!
estimatedTotal: Decimal!
appliedCouponCode: String
"""
Any items with status OUT_OF_STOCK or PRICE_CHANGED require
user acknowledgment before checkout can proceed.
"""
hasIssues: Boolean!
updatedAt: DateTime!
}
type CartItem implements Node {
id: ID!
productVariant: ProductVariant!
quantity: Int!
unitPrice: Decimal! # price at time of adding to cart
currentPrice: Decimal! # current live price
lineTotal: Decimal! # quantity × currentPrice
status: CartItemStatus!
}
"""
A completed or in-progress purchase. Line items are immutable snapshots.
"""
type Order implements Node {
id: ID!
orderNumber: String! # human-readable, e.g., "ORD-20240315-4821"
status: OrderStatus!
lineItems: [OrderLineItem!]!
shippingAddress: Address!
billingAddress: Address!
subtotal: Decimal!
discountAmount: Decimal!
taxAmount: Decimal!
shippingAmount: Decimal!
total: Decimal!
appliedCouponCode: String
"""Null until order ships."""
trackingNumber: String
"""Null until order ships."""
estimatedDeliveryAt: DateTime
placedAt: DateTime!
updatedAt: DateTime!
}
"""
Immutable snapshot of a ProductVariant at purchase time.
Preserves price and product name even if the variant is later modified.
"""
type OrderLineItem implements Node {
id: ID!
"""
References the live ProductVariant. May be null if variant was deleted.
Always use the snapshot fields (snapshotName, snapshotPrice) for display.
"""
productVariant: ProductVariant
snapshotName: String! # "Blue Widget - Large / Red"
snapshotSku: String!
snapshotPrice: Decimal!
quantity: Int!
lineTotal: Decimal!
}
# ─── Connection Types (Relay Cursor spec) ───────────────────────────────
type ProductConnection {
edges: [ProductEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
type ProductEdge {
node: Product!
cursor: String!
}
type OrderConnection {
edges: [OrderEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
type OrderEdge {
node: Order!
cursor: String!
}
type PageInfo {
hasNextPage: Boolean!
hasPreviousPage: Boolean!
startCursor: String
endCursor: String
}
# ─── Input Types ─────────────────────────────────────────────────────────
input ProductFilterInput {
categoryId: ID
minPrice: Decimal
maxPrice: Decimal
isAvailable: Boolean
searchQuery: String
}
input ProductOrderByInput {
field: ProductSortField!
direction: SortDirection!
}
input OrderFilterInput {
status: OrderStatus
placedAfter: DateTime
placedBefore: DateTime
}
input AddCartItemInput {
productVariantId: ID!
quantity: Int!
}
input UpdateCartItemInput {
cartItemId: ID!
quantity: Int! # set to 0 to remove
}
input ApplyCouponInput {
cartId: ID!
couponCode: String!
}
input CheckoutInput {
cartId: ID!
shippingAddressId: ID!
billingAddressId: ID!
"""
Client must confirm awareness of cart issues (out of stock, price changes)
by setting this to true if Cart.hasIssues is true.
"""
acknowledgeIssues: Boolean
}
input CreateAddressInput {
type: AddressType!
firstName: String!
lastName: String!
line1: String!
line2: String
city: String!
stateOrProvince: String!
postalCode: String!
country: String!
isDefault: Boolean
}
input UpdateUserProfileInput {
firstName: String
lastName: String
email: String
}
# ─── Payload Types ───────────────────────────────────────────────────────
type AddCartItemPayload {
cart: Cart
cartItem: CartItem
errors: [UserError!]!
}
type UpdateCartItemPayload {
cart: Cart
errors: [UserError!]!
}
type ApplyCouponPayload {
cart: Cart
errors: [UserError!]!
}
type CheckoutPayload {
order: Order
errors: [UserError!]!
}
type CreateAddressPayload {
address: Address
errors: [UserError!]!
}
type UpdateUserProfilePayload {
user: User
errors: [UserError!]!
}
type CancelOrderPayload {
order: Order
errors: [UserError!]!
}
# ─── Viewer Type (authenticated context) ─────────────────────────────────
"""
The authenticated user's session context.
Use viewer-scoped queries instead of passing userId arguments.
"""
type Viewer {
user: User!
cart: Cart!
}
# ─── Query Root ──────────────────────────────────────────────────────────
type Query {
"""Fetch any entity by its global Node ID."""
node(id: ID!): Node
"""The authenticated user's session. Returns null for unauthenticated requests."""
viewer: Viewer
product(id: ID!): Product
productBySlug(slug: String!): Product
products(
filter: ProductFilterInput
orderBy: ProductOrderByInput
first: Int = 20
after: String
): ProductConnection!
category(id: ID!): Category
categoryBySlug(slug: String!): Category
"""Top-level categories only. Use Category.childCategories for subtrees."""
rootCategories: [Category!]!
"""
Look up a cart by its opaque token. Used for anonymous/guest carts.
Authenticated users should use viewer { cart } instead.
"""
cart(token: String!): Cart
}
# ─── Mutation Root ────────────────────────────────────────────────────────
type Mutation {
addCartItem(input: AddCartItemInput!): AddCartItemPayload!
updateCartItem(input: UpdateCartItemInput!): UpdateCartItemPayload!
applyCoupon(input: ApplyCouponInput!): ApplyCouponPayload!
checkout(input: CheckoutInput!): CheckoutPayload!
cancelOrder(orderId: ID!): CancelOrderPayload!
createAddress(input: CreateAddressInput!): CreateAddressPayload!
updateUserProfile(input: UpdateUserProfileInput!): UpdateUserProfilePayload!
}| From | Field | To | Cardinality | Paginated |
|---|---|---|---|---|
| User | addresses | Address | 1→many | No (bounded by address book size ~10) |
| User | orders | OrderConnection | 1→many | Yes (cursor) |
| Viewer | cart | Cart | 1→1 | No |
| Product | variants | [ProductVariant] | 1→many | No (bounded ~50) |
| Product | categories | [Category] | many→many | No (bounded ~5 per product) |
| Category | products | ProductConnection | many→many | Yes (cursor) |
| Category | childCategories | [Category] | 1→many | No (depth argument limits scope) |
| Cart | items | [CartItem] | 1→many | No (bounded by cart max ~100 items) |
| CartItem | productVariant | ProductVariant | many→1 | No |
| Order | lineItems | [OrderLineItem] | 1→many | No (bounded at checkout time) |
| OrderLineItem | productVariant | ProductVariant | many→1 | No (nullable -- variant may be deleted) |
| Check | Status | Notes |
|---|---|---|
| Naming conventions | ✅ | All types PascalCase, fields camelCase, enums SCREAMING_SNAKE_CASE |
| All mutations have payload types | ✅ | All 7 mutations return XxxPayload with errors: [UserError!]! |
| All large collections paginated | ✅ | products, category.products, user.orders use cursor connections |
| Bounded collections not paginated | ✅ | cart.items, order.lineItems, product.variants are bounded by domain |
| N+1 risks documented | ⚠️ | CartItem.productVariant, OrderLineItem.productVariant, Product.categories all require DataLoader batching in resolvers |
| Node interface coverage | ✅ | User, Product, ProductVariant, Cart, CartItem, Order, OrderLineItem, Address, Category all implement Node |
| Breaking change baseline | ✅ | Initial schema -- establish as v0 baseline in schema registry before first deploy |
| Description coverage | ✅ | All types described; non-obvious fields have inline documentation |
Planned additions (non-breaking): Product.reviews: ReviewConnection, Order.refunds: [Refund!]!, User.wishlist: ProductConnection!
Known N+1 risks requiring DataLoader: CartItem.productVariant (batched by variantId), Product.categories (batched by productId), OrderLineItem.productVariant (batched by variantId)
Future consideration: When adding a loyalty/rewards system, add User.rewardPoints: Int! and CheckoutInput.rewardPointsToApply: Int -- the payload pattern means no breaking changes to the checkout mutation signature
Guest checkout: The cart(token: String!) query supports anonymous carts now; when adding guest checkout (order without User), add guestEmail: String to CheckoutInput and make Order.user: User nullable -- this will be a nullable-ization (non-null → nullable), which is a safe non-breaking change
SKILL.md
783 lines · 5,769 words
The text of SKILL.md is shown as it downloads, under the Apache-2.0 license, by Ferrox Labs. The license is the one in the file's own frontmatter.
Your new bot
GraphQL Schema Design bot
Waiting in your sidebar once you say go.
No account needed · Runs on the AI plan you already pay for