What are the four types of checks and what does each catch?

Composition checks validate the schema can compose with all other subgraphs. Breaking change detection finds removed fields, changed types, and other changes that would break clients. Operation Checks use real client traffic to determine whether breaking changes affect active queries. Lint checks enforce schema design standards you configure.

How does traffic analysis know which client operations are affected?

Cosmo collects operation data from your router traffic. The analytics pipeline records which fields each operation touches. When a breaking change is detected, the check queries this data for the configured time window (default: 7 days) and reports which specific operations would break.

Can I override a failing check when a breaking change is intentional?

Yes. The GitHub integration supports manual check overrides with documented justification. Overrides are recorded in the check history.

Does the check run against production data without affecting production?

Yes. The check is a read-only operation. It queries analytics data and tests composition hypothetically. Nothing is published until you explicitly run `wgc subgraph publish`.

Can I check a subgraph that doesn't exist yet?

Yes. Use the `--label` flag to specify which federated graphs the new subgraph would join. Composition is tested without creating the subgraph.

How do I check what a deletion would affect?

Run `wgc subgraph check [name] --delete`. This shows the impact on all connected federated graphs before you delete anything.

Does schema checks work with a self-hosted Cosmo deployment?

Yes. Schema checks run against the control plane and work with both Cosmo Cloud and self-hosted deployments. Composition and lint checks work out of the box. Operation Checks require the router to send operation analytics to the same control plane.

GraphQL Schema Checks | Cosmo by WunderGraph

The problem

Why schema changes break production graphs

Schema changes in federated GraphQL have consequences that reach further than the subgraph being changed. Traditional testing misses this.

Field removals break mobile clients still on older queries

Mobile apps don't update in lockstep with APIs. A field that looks unused in current web traffic might still power a client that's three versions behind. Without traffic analysis, you can't know.

Type changes cascade across subgraph boundaries

A shared type used in three subgraphs can fail to compose if one of them changes an argument or return type. Static analysis catches this only if it understands the full federation graph.

Schema quality degrades without enforcement

Without automated lint checks, naming conventions drift, descriptions go missing, and the schema becomes harder to consume. Manual review doesn't scale across multiple teams and daily deploys.

Our solution

Four-layer validation before every publish

Cosmo's Schema Checks run four layers of validation — composition, breaking changes, real client traffic analysis, and lint checks — before any schema change is published, so teams can ship with confidence without manual review. The check runs in CI against the wgc subgraph check command and returns a clear pass/fail with specifics for each layer.

What each layer catches

Composition validation catches type conflicts and federation directive errors before the schema is published.
Breaking change detection compares the proposed schema against the current production schema.
Operation Checks query real client traffic — default 7-day window, configurable per namespace — to determine whether breaking changes affect active operations.
Lint checks enforce schema design standards across all teams.

Issues surface in CI/CD and pull requests — not in production routers.

Schema checks

Before & After

Before Cosmo	With Cosmo
Breaking changes discovered in production	Breaking changes caught in CI/CD
No visibility into client impact	Real traffic analysis shows affected operations
Manual schema review for quality	Automated lint checks
Composition failures after deployment	Composition validated before publish

Check pipeline

Four types of validation

Composition — type conflicts and federation directive errors before merge.
Breaking changes — proposed schema vs. current production schema.
Operation checks — real client traffic over the configured window (default: 7 days).
Lint checks — namespace policies for design standards.

Key benefits

Ship schema changes with confidence

Four validation layers — composition, breaking changes, operation checks, and lint checks — included on Free, Pro, and Enterprise.

Real traffic shows whether breaking changes actually matter

Operation checks

Operation Checks analyze client traffic against the proposed schema — 7 days by default, configurable per namespace. A breaking change that no active client uses passes automatically. One that breaks real queries shows exactly which operations are affected.

Composition errors surface in CI, not in production

Composition

The check attempts composition with all other subgraphs before anything is published. Type conflicts and federation directive errors appear in the PR — not after the deploy.

Lint checks enforce schema quality without manual review

Lint checks

Configure naming conventions, description requirements, and design standards in namespace policies. Every check validates against these rules and flags violations with specific line and column numbers.

Schema check results live inside your pull requests

GitHub

Schema check results appear directly in pull requests via native GitHub integration. Failing checks block merges. Passing checks give the green light automatically.

Override when a breaking change is intentional

Override

When a breaking change is necessary, teams can override the check with documented justification. The override is recorded in the check history for audit purposes.

How schema checks work

01

One command in your pipeline.

Run the check in CI

Run `wgc subgraph check [name] --schema ./new-schema.graphql` in CI. The proposed schema is sent to the control plane.

02

Peers validated before publish.

Composition is validated

The control plane validates composition with all other subgraphs. Type conflicts and directive violations appear immediately.

03

Field paths, not vague warnings.

Breaking changes are detected

The proposed schema is compared against the current production schema. Removed fields and type changes are listed with specific field paths.

04

7-day window by default.

Traffic impact is analyzed

If breaking changes exist, the control plane checks real client traffic over the configured window (7 days by default). Zero affected operations: the check passes. Active operations affected: the specific queries are listed.

05

Line and column in the PR.

Lint checks are enforced

The schema is validated against namespace lint policies. Violations are returned with line and column numbers.

Use cases

Where teams run schema checks first

Pull request validation

CI / GitHub

A developer submits a PR that removes a deprecated field. The CI pipeline runs `wgc subgraph check`. Cosmo validates composition, detects the field removal as a breaking change, and queries client traffic over the configured window (7 days by default). If no active clients use the field, the check passes. If clients are affected, the PR shows exactly which operations would break.

Safe breaking changes with override

Override

A team must remove a field that some clients still use. The check fails due to active client usage. After coordinating with affected clients, the team overrides the check via GitHub integration. The override is documented in the check history.

Schema quality enforcement

Lint checks

An organization requires all GraphQL types and fields to follow specific naming conventions and include descriptions. Lint check rules are configured in namespace policies. Every check flags violations with exact line and column numbers.

New subgraph validation

--label

A new subgraph that doesn't exist in the registry yet can be validated with label flags: `wgc subgraph check new-service --schema ./schema.graphql --label team=A`. Composition is tested without publishing anything.

Metrics & monitoring

Studio

Studio keeps a complete history of every check — pass/fail status and full details for each run. Use it to see which subgraphs are generating failures and review the specifics of any past check.

When to use schema checks

When to use

You want to catch breaking schema changes before they reach production clients.
You have a CI/CD pipeline and want automated schema validation on every pull request.
Multiple teams publish to the same federated graph and you need composition guardrails.

When not to use

Operation Checks require the router to be sending traffic to Cosmo — without it, traffic analysis has no data and any breaking change will auto-pass. Composition and lint checks still run regardless.

Add schema checks to your CI pipeline in minutes

One CLI command. Native GitHub integration. No manual review process.

Start Free See the docs

Ready to go deeper?

Full reference for check commands, lint check configuration, and GitHub integration.

Read the Docs →

Know before you ship whether a schema change breaks real clients