# Find unused fields before they become technical debt

Graph Pruning uses real traffic data to identify unused fields, track deprecated fields still in use, and enforce deprecation before deletion. Available on Pro and Enterprise.

## The problem

### Schemas grow. Fields rarely leave.

Without usage data, there is no safe way to know which fields to remove, which deprecated fields still have traffic, or which deletions need a warning first.

### Schemas accumulate unused fields over time

Teams add fields speculatively. Features are removed but fields remain. Without usage data, there is no way to know which fields are safe to remove.

### Deprecated fields linger indefinitely

Fields are marked @deprecated but never removed. Without tracking which deprecated fields still receive traffic, teams cannot safely complete the cleanup.

### Deleting fields without prior deprecation breaks consumers

Removing a field that was never formally deprecated gives consumers no warning. A deletion policy that requires deprecation first protects downstream teams.

## Our solution

### Usage-based schema pruning

Graph Pruning runs during schema checks and queries real traffic data to flag unused fields, track lingering deprecated fields, and block deletions that skipped the deprecation step.

### From check to clean schema

1. Graph Pruning rules run during schema check operations alongside other lint and breaking change checks.
2. The linter analyzes the schema and queries the analytics pipeline for field usage data.
3. `UNUSED_FIELDS` identifies fields with no usage within the check period.
4. `DEPRECATED_FIELDS` flags deprecated fields still present in the schema.
5. `REQUIRE_DEPRECATION_BEFORE_DELETION` fails checks that attempt to delete fields not previously marked as @deprecated.
6. A grace period can be configured to prevent false positives on recently published fields.

Real traffic data. Informed decisions. Cleaner schemas.

## Before & After

| Before Cosmo | With Cosmo |
| --- | --- |
| Unknown which fields clients actually use | `UNUSED_FIELDS` rule flags fields with no traffic in the check period |
| Deprecated fields remain in the schema indefinitely | `DEPRECATED_FIELDS` rule identifies deprecated fields still present |
| Fields deleted without warning to consumers | `REQUIRE_DEPRECATION_BEFORE_DELETION` fails checks that skip deprecation |
| False positives on recently added fields | Configurable grace period before rules are enforced |

### The three Graph Pruning rules

- `UNUSED_FIELDS`: Identifies fields with no usage within the configured check period.
- `DEPRECATED_FIELDS`: Flags deprecated fields that still appear in the schema.
- `REQUIRE_DEPRECATION_BEFORE_DELETION`: Fails checks when fields are deleted without prior @deprecated marking.

Schema Usage Check Period is configurable on Enterprise. On other plans, the period is determined by billing plan limits.

## How Graph Pruning works in Cosmo

01. **Enable**: Enable Graph Pruning in Cosmo Studio for the namespace. Select which of the three rules to activate.

02. **Configure**: Set severity (error or warning) and grace period for each rule. Enterprise customers can also configure the schema usage check period.

03. **Check**: Run `wgc subgraph check`. Graph Pruning evaluates the schema against usage data from the analytics pipeline.

04. **Act**: Review flagged fields. Remove fields with no usage, communicate deprecation for fields still in use, or add @deprecated before deletion.

## What Graph Pruning gives you

### Usage-based analysis

Rules check field usage against real traffic data from the analytics pipeline. Decisions are based on actual queries, not estimates.

### Grace period

Configure a time window after schema publication before rules are enforced. Prevents false positives on fields published but not yet widely adopted.

### Three rules, independent configuration

`UNUSED_FIELDS`, `DEPRECATED_FIELDS`, and `REQUIRE_DEPRECATION_BEFORE_DELETION` each have their own severity and grace period settings.

### Configurable check period

Enterprise customers can set the time window for usage analysis. Other plans use the period defined by their billing plan.

## Remove fields with confidence

Use real traffic data to identify what is safe to remove. Available on Pro and Enterprise.