Schema Linting and Style Rules

Conventions No Reviewer Can Enforce by Eye

A schema review lands with four hundred lines of SDL. Somewhere in it, a type is userProfile instead of UserProfile, three fields have no description, one is named userId inside type User, and a deprecation was added without a reason. The reviewer catches one of the four, because scanning for style across hundreds of declarations is exactly the job humans are bad at.

Style drift is not cosmetic. Names are what developers type into completion all day; descriptions are what ends up in the docs panel; @deprecated without a reason leaves the next migration with nothing to follow. And the drift compounds: every inconsistent field becomes precedent for the next contributor.

A schema linter parses SDL and operation documents into an AST and applies configurable rules — the same architecture as ESLint, with GraphQL-specific rules. Two properties make it worth wiring up:

• Consistency across scale. One rule applied to 400 fields beats any number of review comments, and it applies identically to the 401st field added six months later.
• Different documents, different rules. Schema files are checked for naming, descriptions, and type hygiene; operation files are checked for structural mistakes (anonymous queries, unused fragments, runaway depth). The two sets barely overlap, which is why configurations use separate overrides per file pattern.

It helps to be precise about what linting is not. A linter does not know whether removing a field breaks a client — that is a compatibility question and belongs to schema checks in CI. It does not know whether a query returns the fields you intended — that is what TypeScript codegen turns into compile errors. Linting owns the middle layer: conventions and structural hygiene, enforced on every commit.

The Rule Set Worth Turning On

GraphQL ESLint ships recommended presets for each side — schema-recommended and operations-recommended — and the rules that earn their place early look like this:

# .graphqlrc.yml — one source of truth for editor and CI
schema: 'src/schema/**/*.graphql'
documents: 'src/**/*.{graphql,ts,tsx}'

// .eslintrc.cjs
module.exports = {
  overrides: [
    {
      files: ['src/schema/**/*.graphql'],
      extends: ['plugin:@graphql-eslint/schema-recommended'],
      rules: {
        '@graphql-eslint/require-description': 'error',
        '@graphql-eslint/no-typename-prefix': 'error',
        '@graphql-eslint/require-deprecation-reason': 'error',
        '@graphql-eslint/naming-convention': ['error', {
          types: 'PascalCase',
          FieldDefinition: 'camelCase',
          'FieldDefinition[gqlType.name.value=Boolean]': { style: 'camelCase', requiredPattern: '/^(is|has)/' },
        }],
      },
    },
    {
      files: ['src/**/*.{ts,tsx}'],
      extends: ['plugin:@graphql-eslint/operations-recommended'],
      rules: {
        '@graphql-eslint/no-anonymous-operations': 'error',
        '@graphql-eslint/naming-convention': ['error', { OperationDefinition: 'PascalCase' }],
        '@graphql-eslint/selection-set-depth': ['error', { max: 7 }],
      },
    },
  ],
};

What each rule buys:

The naming options are selector-based, which is what makes them practical: apply a stricter pattern only to FieldDefinition on the Query root, or require a prefix for a specific scalar's fields, instead of one global casing rule that every legitimate exception fights.

Making Lint Fail the Build

A lint configuration that only runs in someone's editor is a suggestion. Three steps turn it into an enforcement point.

1. Same config everywhere. The graphql-config file (.graphqlrc.yml) tells both the editor plugin and CI where schemas and documents live, so the squiggles a developer sees are the failures CI will report. Divergent configs are how "passes locally, fails in CI" erodes trust in the gate.

2. CI as one more npm script.

# .github/workflows/lint.yml
name: lint
on: [pull_request]
jobs:
  eslint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npx eslint 'src/**/*.graphql' 'src/**/*.{ts,tsx}'

3. Ratchet, do not flood. Turning twelve new rules to error on an existing codebase fails every open pull request and teaches people to disable the linter. Start new rules at warn, fix the backlog in one dedicated cleanup, then promote to error — and use --max-warnings 0 in CI during the warn phase so the warning count cannot grow while you pay the backlog down.

Autofix coverage determines how fast that cleanup goes. Rules like alphabetize ship fixers; naming and description rules do not (renaming a public field is a compatibility event, not a formatting one — see the evolution rules matrix before running any bulk rename). Plan the cleanup as schema work with a review, not as a lint task.

Two structural habits keep the configuration healthy:

• Keep the overrides separate. Schema rules applied to operation files (or the reverse) produce errors that cannot be fixed without breaking the document, and the reflex becomes disabling the rule.
• Add project-specific rules sparingly. GraphQL ESLint supports custom rules; a local rule that requires a description on every root field or forbids a house prefix pays for itself only when reviewers keep catching the same thing manually.

Interview framing: "how do you enforce schema conventions?" Answer in three layers — a shared config consumed by editor and CI, rule sets split between schema and operations, and a ratchet from warn to error with a cleanup plan. Then name one rule and the specific defect it prevents; that separates tooling knowledge from tooling vocabulary.