Breaking Changes Workflow
A step-by-step guide to making breaking changes safely. Covers what triggers the impact confirmation dialog, how to choose between migration paths, and how to track resolution on the task board.
When you edit a schema, API endpoint, or operation in a way that could break downstream consumers, NeoArc detects the change at save time and shows an impact confirmation dialog before proceeding. This guide walks through the complete workflow, from triggering the dialog to resolving impacts on the task board.
Step 1: Make a Change
Edit any schema or API resource normally. Changes that qualify as breaking include:
| Resource Type | Breaking Changes |
|---|---|
| Schema | Field removed, field renamed, field type changed, required flag added, schema type changed, enum value removed, union member removed |
| REST Endpoint | HTTP method changed, path changed, request/response schema changed, security requirement added |
| GraphQL Operation | Operation type changed (query to mutation), argument removed or made non-nullable, return type changed |
| AsyncAPI Channel | Channel address changed, message removed, operation action changed (send to receive) |
| Webhook Event | Event name changed, payload schema changed, verification method changed, header removed |
| gRPC Method | Method renamed, request/response schema changed, streaming mode changed |
| MCP Tool | Tool renamed, input/output schema changed, resource URI template changed, prompt argument removed |
Step 2: The Impact Dialog Appears
When the auto-save triggers (after 500ms of inactivity), the system compares the current state against the last saved snapshot. If breaking changes are detected and the resource has downstream consumers in the Intent Graph, the impact confirmation dialog appears.
The dialog shows:
- A summary of the breaking changes detected in this edit
- A list of affected downstream resources (schemas, endpoints, views, diagrams, pages) grouped by category
- Cumulative change context from the last approved baseline, if baselines exist (e.g. "Since baseline v1.0.0: 3 breaking, 2 additive, 1 deprecation changes")
Step 3: Choose a Path
The dialog presents three options. The right choice depends on how urgent the change is and whether you want to fix downstream effects first or after.
Step 4: Resolve Impacts on the Task Board
After choosing "Proceed and Track" or "Track Only", impact cards appear on the Architect Task Board. Each card identifies a specific downstream resource that needs attention.
| Card Type | Created When | Contains |
|---|---|---|
| Impact Card | Both paths | Affected resource name, relationship type, severity, explanation, and an Analyse Impact button that opens the full impact analysis sheet |
| Action Card | Track Only | A dependency checklist linking to every impact card. Items check off automatically as their linked cards reach the Done column |
Work through the impact cards by updating each affected resource. Move cards across the board columns as you progress: Broken or Needs Review to In Progress, then to Done. For "Track Only" cards, the action card's checklist auto-syncs, making it clear when all dependencies are resolved and the original change can be safely applied.
Step 5: Baseline Context
If your project uses baselines with per-resource approval, the impact dialog includes additional context. It resolves the last baseline where this specific API or schema was formally approved, then runs a semantic diff from that baseline to the current working state.
This means you see not just the changes from this edit session, but the cumulative breaking changes since the last approved contract. This is particularly useful when multiple team members have made small changes that individually seem safe but collectively introduce breaking behaviour.
Supported Editors
Save-time impact analysis is available in all schema and API editors across all six supported API types.