GR
GraphQL Defaults
Core GraphQL schema and query conventions
Details
Language / Topic
GraphQLCategory
Style Guide
Rules
balanced
- Name types in `PascalCase`, fields in `camelCase`, and enum values in `SCREAMING_SNAKE_CASE` — consistent with GraphQL spec conventions.
- Always define a `description` string on every type, field, and argument — it appears in introspection and generated documentation.
- Prefer `input` types over inline scalar arguments for mutations: `createUser(input: CreateUserInput!)` rather than `createUser(name: String!, email: String!)`.
- Avoid overly broad `String` scalars for domain values — define custom scalars like `EmailAddress`, `DateTime`, or `URL` for validation and clarity.
- Use `!` (non-null) modifiers deliberately — only mark fields non-null when the server can guarantee a value; unexpected nulls cause partial response failures.
- Follow a consistent pattern for list fields: `posts: [Post!]!` means a non-null list of non-null posts; document which variant your schema uses.
- Prefix mutation names with a verb: `createPost`, `updatePost`, `deletePost` — not `postCreate` or `PostMutation`.
- Return a dedicated payload type from mutations: `type CreatePostPayload { post: Post, errors: [UserError!]! }` to carry both success data and error details.
- Use `@deprecated(reason: "Use X instead")` directive rather than removing fields immediately — preserve backwards compatibility across clients.