DEV Community: Deepak Satyam

Optic is dead. A 2026 migration guide for OpenAPI breaking changes

Deepak Satyam — Sat, 23 May 2026 18:29:19 +0000

This article was originally published on the SpecShield blog. I'm a co-founder of SpecShield, one of the migration targets discussed below — full disclosure upfront. The post tries to be honest about where SpecShield fits and where other tools fit better.

TL;DR

Optic's GitHub repo was archived on January 12, 2026. Last release: v1.0.9 in August 2025. The useoptic.com domain no longer resolves.

Optic was acquired by Atlassian in April 2024 but was never folded into Atlassian Compass.

The MIT-licensed source is still on GitHub, but abandoned — no security patches, no new rules, no support, and your CI will eventually break when a transitive dependency goes EOL.

If you used Optic primarily for spec-to-spec diffing and breaking-change checks in CI, the most direct migration path is to SpecShield (Web UI + CLI + GitHub App + free GitHub Action) or oasdiff (open-source CLI, no UI).

If you used Optic for OpenAPI generation from test traffic — there is no direct replacement. You'll need to change workflow.

Below: a feature-by-feature comparison table, a step-by-step migration walkthrough, and an honest list of what's hard to replace.

What actually happened to Optic

For the last six years, Optic was the open-source default for OpenAPI breaking-change detection. It had what most developer-tool startups don't: a clean CLI, a sensible rule system, MIT licensing, deep CI integration, and a small but devoted community.

Here's the timeline of how it ended:

Date	Event
April 2024	Atlassian acquires Optic Labs. Optic team joins Atlassian.
April 2024 – August 2025	Release cadence slows. Most commits become dependency bumps. Issues pile up unanswered.
August 10, 2025	Final release: v1.0.9. No release notes hint that it's the last.
August 2025 – January 2026	Silence. No releases, no maintainer responses. The community asks "is Optic still maintained?" — no official answer.
January 12, 2026	The `opticdev/optic` GitHub repo is archived (made read-only). The `useoptic.com` domain stops resolving shortly after.

There was no formal sunset announcement, no migration guide from the Optic team, no archived-but-here's-a-fork blessing. It just stopped.

The expectation in the community after the Atlassian acquisition was that Optic would become part of Atlassian Compass — Atlassian's developer-experience product. That integration never shipped. As of May 2026, Compass remains focused on service catalogs and DORA metrics, with no API drift detection capability.

The 1.5k-star repo has 92 forks, but no fork has emerged as a community successor. If you keep depending on @useoptic/optic from npm, you're depending on unmaintained code that will eventually break when its TypeScript / Node / npm peer dependencies hit EOL.

You need to migrate. The good news: this is a four-hour job for most teams, not a four-week project.

What you actually used Optic for (and what you'll need to replace)

Optic had five distinct capabilities. Different teams used different subsets. Identify which ones applied to you before picking a replacement — choosing wrong is the single biggest migration mistake.

1. Spec-to-spec diffing and breaking-change detection

The most common use case. You had openapi.yaml in your repo, you ran optic diff in CI on every PR, and the action commented on the PR with breaking-change warnings.

Replacement difficulty: Easy. Multiple drop-in alternatives exist.

2. OpenAPI rule-based linting

Optic had its own ruleset format (.optic.dev.yml) for things like "all paths must be kebab-case" or "every endpoint needs a description".

Replacement difficulty: Medium. You'll switch to Spectral, which is the de-facto standard for OpenAPI linting and has a much larger ecosystem of rulesets. Your custom rules will need to be re-expressed in Spectral's format.

3. OpenAPI generation from captured traffic (`optic capture`)

This was Optic's most novel feature. You'd run your test suite with the Optic proxy in front of it, and Optic would generate (or update) the OpenAPI spec from observed traffic.

Replacement difficulty: Hard. There is no direct open-source replacement with the same maturity. Alternatives include:

Pollyjs (record/replay HTTP, generic)
Speakeasy (different workflow — spec drives SDK, not traffic drives spec)
Hand-maintaining the OpenAPI spec (which is what most teams end up doing)

If you relied heavily on optic capture, your migration is more painful than spec-diff users. Plan accordingly.

4. CI integration via GitHub Action

The useoptic/optic-action GitHub Action posted PR comments with diff results.

Replacement difficulty: Easy. Several drop-in alternatives exist with similar or better PR comment design.

5. Hosted UI for browsing diffs and history

Optic Cloud (the SaaS layer) gave you a web UI to browse diffs across releases and share them with non-developer stakeholders.

Replacement difficulty: Medium. The hosted UI tools available today either cost more (Bump.sh, Stoplight) or look less polished. SpecShield's web UI is a direct equivalent in scope and is in active development.

Your migration options at a glance

Honest comparison of the realistic alternatives, as of May 2026:

Tool	What it replaces	Pricing	Hosted UI	OSS engine	PR comments	Active development
SpecShield	Optic's spec-diff, breaking-change detection, hosted UI, CI integration, BDCT (bonus)	Free tier; paid from $29/mo	✅ Yes	Closed core, free GitHub Action coming	✅ Yes (GitHub App + Action)	✅ Active
oasdiff	Spec-diff and breaking-change detection (CLI only)	Free / OSS (Apache 2.0)	❌ No	✅ Yes (Go)	✅ Via official GitHub Action	✅ Active
Spectral	Optic's linting (not diffing)	Free / OSS (Apache 2.0)	❌ No	✅ Yes (TS)	Via custom integration	Active but slower post-SmartBear acquisition
Bump.sh	Hosted docs + changelog (a different workflow than Optic's CI flow)	From $50/mo	✅ Yes	❌ No	❌ No native PR comments	✅ Active
Redocly CLI	Linting + diff (basic)	Free CLI; paid platform	✅ Yes (paid)	Partial OSS	Via custom integration	✅ Active

Three patterns will cover ~95% of Optic migrations:

You used Optic for spec-diff in CI + you want a UI → SpecShield (most direct replacement, smallest mental model shift)
You used Optic for spec-diff in CI + you don't need a UI → oasdiff (CLI-only, Apache 2.0, will outlive any SaaS company)
You used Optic for linting → Spectral (regardless of which diff tool you pick)

The rest of this post focuses on path #1, because it's the most common and the least documented. If you're on path #2 or #3, the official docs for oasdiff and Spectral are excellent and you don't need a migration guide.

Why SpecShield is the most direct replacement for Optic users

I built SpecShield specifically for the spec-first, CI-driven workflow Optic championed. The mental model is identical:

You commit your OpenAPI spec to git
On every PR, the new spec is compared to the base branch
Breaking changes are flagged before merge
You get a beautiful diff report (in the UI, the CLI, and as a PR comment)

What's the same as Optic:

OpenAPI 3.0 and 3.1 support
Multi-file spec support (with $ref)
Breaking-change classification (removed paths, type changes, new required fields, etc.)
CI/CD integration via GitHub App and (soon) free GitHub Action
CLI distributed via npm (npx specshield compare ...)

What's better than Optic:

Bi-Directional Contract Testing (BDCT) — verify provider/consumer compatibility, with a can-i-deploy gate. Optic never had this.
Compatibility matrix for multi-service architectures
Beautiful, screenshot-worthy PR comments (Optic's were utilitarian)
Active development — we ship roughly weekly
Free tier with no time limit (Optic Cloud's free tier was always limited)

What's different (some teams will see these as downgrades):

SpecShield is a SaaS product with a free tier. Optic was BYO-infrastructure if you stayed on the open-source CLI.
The core diff engine isn't open-source today (the free GitHub Action will be, when it ships later in 2026).
We're a smaller team than Optic was at its peak — though we ship faster.

If you're moving primarily because Optic stopped getting maintained and you want something that will be maintained, those tradeoffs probably work in your favor. If you fundamentally need OSS-or-nothing, see oasdiff.

Step-by-step migration: Optic → SpecShield

Here's the actual migration for a team that was using Optic's CLI and GitHub Action. Expect this to take 30–60 minutes end-to-end, including PR review time.

Step 0 — Audit what you're currently using

Before deleting anything, find every place Optic is referenced in your repo:

# Find Optic config files
find . -name ".optic.dev.yml" -o -name "optic.yml" -o -name ".optic*"

# Find Optic CI workflows
grep -rE "useoptic/optic-action|optic diff|optic lint" .github/

# Find Optic CLI invocations in scripts
grep -rE "@useoptic/optic|optic capture|optic verify" package.json scripts/

# Find references in docs
grep -ri "optic" README.md docs/ 2>/dev/null

Make a checklist of every file you found. You'll touch each one.

Step 1 — Install the SpecShield CLI

The SpecShield CLI is published to npm as specshield. You don't need to globally install it — npx is fine for CI:

# Test it locally — no signup needed for the diff command
npx specshield compare old-openapi.yaml new-openapi.yaml

You'll see output that includes the same categories Optic produced (breaking, non-breaking, additions), formatted as a clean terminal table.

If you want JSON output for CI scripting, use the --json flag (with --output to also write to a file):

# Print JSON to stdout AND save to a file
npx specshield compare old.yaml new.yaml --json --output diff.json

The JSON shape is:

{
  "summary": { "breaking": 3, "additions": 12, "modifications": 7, "warnings": 0 },
  "breakingChanges": [...],
  "additions": [...],
  "modifications": [...],
  "warnings": [...]
}

Step 2 — Replace your Optic GitHub workflow

If you had something like this .github/workflows/api-check.yml:

# OLD — Optic workflow
name: API contract check
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: useoptic/optic-action@v1
        with:
          spec: openapi.yaml
          base_ref: ${{ github.event.pull_request.base.ref }}

Replace it with this:

# NEW — SpecShield CLI workflow
name: API contract check
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Extract base spec from base branch
        run: git show origin/${{ github.event.pull_request.base.ref }}:openapi.yaml > /tmp/base.yaml

      - name: Compare specs
        id: compare
        continue-on-error: true
        run: |
          {
            echo '## 🛡️ SpecShield · API contract check'
            echo ''
            echo '```
{% endraw %}
'
            npx specshield compare /tmp/base.yaml openapi.yaml --fail-on-breaking
            echo '
{% raw %}
```'
          } > /tmp/comment.md

      - name: Comment on PR
        if: always()
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          path: /tmp/comment.md

      - name: Fail the build if breaking changes were found
        if: steps.compare.outcome == 'failure'
        run: exit 1

A few notes on this pattern:

The CLI auto-disables ANSI color codes when not running in a TTY, so the output inside the fenced code block renders cleanly on GitHub.
continue-on-error: true on the compare step lets the PR comment post even when breaking changes are detected. The final step then fails the build explicitly so PR checks still gate the merge.
marocchino/sticky-pull-request-comment updates the existing comment in place on subsequent commits rather than spamming the PR.
A dedicated SpecShield Action (in development) will render a richer markdown comment with a color-coded summary table and collapsible per-endpoint diffs. Until that ships, the fenced-code-block approach above is the cleanest path.

Step 3 — Migrate your custom rules (if you had any)

This is the step that takes the longest if you'd customized Optic's rule engine. Optic rules looked like this:

# OLD — .optic.dev.yml
ruleset:
  - breaking-changes
  - examples
  - name: kebab-case-paths
    where:
      operation: { in: any }
    rule:
      after: must
      assert: |
        operation.path.split('/').every(s => /^[a-z0-9-]*$/.test(s))

SpecShield doesn't currently expose a Spectral-compatible custom rule API. For now:

Breaking-change rules: covered by SpecShield's built-in detector — no migration needed
Style/lint rules (kebab-case paths, required descriptions, etc.): migrate these to a separate Spectral step in your CI:

- name: OpenAPI lint
  run: npx @stoplight/spectral-cli lint openapi.yaml --ruleset .spectral.yaml

With a .spectral.yaml like:

extends: spectral:oas
rules:
  paths-kebab-case:
    description: Paths should be kebab-case
    given: $.paths.*~
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: ^(\/[a-z0-9-]*)+$

We're working on first-class custom-rule support in SpecShield. Until then, the two-step approach above is the cleanest path.

Step 4 — Remove Optic dependencies

Once your new workflow is green:

# Remove npm dep
npm uninstall @useoptic/optic

# Remove config
rm .optic.dev.yml

# Remove the old workflow (or just edit it)
rm .github/workflows/optic-check.yml

Commit the migration as a single PR — easier to review, easier to revert if anything's off.

Step 5 — Set up the dashboard (optional but recommended)

If you want history, team collaboration, BDCT, and a can-i-deploy gate beyond the per-PR diff:

Sign up free at specshield.io
Install the SpecShield GitHub App on your repo
Your existing CLI runs will automatically appear in your dashboard's compare history

No re-configuration needed — the GitHub App and CLI write to the same backend.

What SpecShield does NOT replace from Optic (being honest)

Three Optic capabilities don't have a clean SpecShield replacement today. If you depended on these, you need a plan.

1. `optic capture` — generating specs from traffic

No direct replacement in SpecShield. Our model assumes you maintain the spec by hand (or generate it from code via a framework annotation library). If optic capture was central to your workflow, evaluate:

Continuing to use Optic's archived capture command standalone (it'll keep working for a while — it's not network-dependent)
Replacing with Pollyjs for record/replay
Switching to a spec-first workflow (which is where the industry has moved, for what it's worth)

optic capture-style functionality is on our roadmap but isn't shipping in 2026.

2. The MIT-licensed core

Optic's diff engine was MIT. SpecShield's core engine is closed-source as of May 2026. The free GitHub Action will be Apache 2.0 when it ships, but the engine behind the hosted product is proprietary.

If "must be fully open-source" is a non-negotiable requirement, use oasdiff — it's the most mature open-source option and is unaffected by Optic's shutdown.

3. The exact ruleset format

Optic's rule DSL is unique. Your rules don't port 1:1 to anything. You'll re-author them in either:

SpecShield's built-in rules (which cover ~80% of the common cases by default)
Spectral's rule DSL (for the remaining 20% of custom style rules)

Plan ~1 hour per custom rule for the rewrite.

When SpecShield is NOT the right migration target

Honest recommendations for the cases where another tool is better:

Your situation	Recommended migration target
"I just want a CLI that does breaking-change detection, no SaaS"	oasdiff. It will outlive every SaaS in this list.
"We had thousands of dollars of Optic Cloud customization and need a high-touch enterprise vendor"	Bump.sh or Stoplight for documentation
"We need OpenAPI capture from traffic"	Stay on Optic's archived CLI for now; Speakeasy if you can shift to spec-first
"We need OpenAPI linting and nothing else"	Spectral (standalone, free)
"We want a fully self-hosted option with no cloud component"	oasdiff + Spectral, both run on your own infra
"We're a microservice org with consumer/provider contracts"	SpecShield (has BDCT built in) or PactFlow (the dedicated Pact-broker SaaS)

The honest read on the post-Optic landscape: there's no single tool that covers everything Optic did. Most teams will end up with two tools in their pipeline — one for diff/breaking-change detection, one for linting — where they had one before.

What we learned from Optic's end

A few takeaways worth sitting with, especially if you build or pay for developer tools:

OSS + VC is a fragile combination. Optic raised funding, was acquired, and shut down within a typical VC fund lifecycle. The OSS code still exists but nobody is paid to maintain it. If a tool is mission-critical to your CI, weight its funding model and sustainability along with its features.
Acquisition isn't continuity. "Acquired by [BigCo]" sounds reassuring at the time. It almost never is. Plan for the acquired tool to be gone within 18 months unless its product roadmap is publicly aligned with the acquirer's stated direction.
Spec-first won. Optic's bet was that you should auto-generate specs from traffic. The industry consensus has moved the other way — the spec is the source of truth, code and tests are generated from it. That shift is part of why the spec-from-capture approach didn't become indispensable.
Beauty matters. Optic's PR comments were functional but plain. The tools that have taken its place (and the ones that will replace whatever replaces them) compete heavily on UI/UX. Engineers screenshot and share comments that look good. That's distribution.

Migrate today, not next quarter

Three reasons to do this migration now, not after your next release:

Optic's npm package will eventually break. @useoptic/optic depends on TypeScript, Node, and dozens of transitive packages, several of which will hit EOL within 12 months. When that happens, your CI will silently start failing in ways that are hard to debug because the underlying tool is unmaintained.
Your team is forgetting Optic's quirks. The longer you wait, the harder the migration. The engineer who set up your Optic workflow may not be at the company in 12 months.
The migration is small if you do it now. Most teams can complete the steps above in under an hour. Wait until a CI break forces it, and you'll be doing it in a panic on a Friday afternoon.

Try SpecShield in 5 minutes

If you've read this far and want to try SpecShield as your Optic replacement:

# No signup needed for the CLI diff command
npx specshield compare old-openapi.yaml new-openapi.yaml

For the dashboard, history, GitHub App, and BDCT: sign up free at specshield.io/signup — no credit card, generous free tier. Pricing details at specshield.io/pricing.

For migration support, email me at founder@specshield.io — happy to help any Optic refugee migrate, gratis, regardless of whether you end up using SpecShield. The migration matters more than the tool.

Was this guide helpful? It's part of a series on the post-Optic API tooling landscape. Next post: a deep technical comparison of the breaking-change rules across SpecShield, oasdiff, and Optic's archived ruleset — including the edge cases each catches that the others miss.

Have feedback or corrections? Drop a comment below or email me directly. I'd rather get this right than get this fast.

How to Detect API Breaking Changes in OpenAPI (Step-by-Step Guide)

Deepak Satyam — Sat, 11 Apr 2026 12:14:50 +0000

APIs are the backbone of modern applications. But one small change in your API can silently break production systems.

If you’re working with microservices or public APIs, detecting breaking changes is not optional — it’s critical.

In this guide, you’ll learn:

What API breaking changes are
Why they are dangerous
How to detect them in OpenAPI/Swagger
How to automate detection in CI/CD

🔍 What is an API Breaking Change?

An API breaking change is any modification that causes existing clients to fail.

Common Examples:

Removing a field from response
Changing data type (e.g., string → integer)
Renaming endpoints
Making optional fields required
Removing query parameters

👉 Even a small change can break mobile apps, frontend apps, or partner integrations.

💥 Why Breaking Changes Are Dangerous

Most API failures in production happen because of undetected contract changes.

Real-world impact:

🚫 Frontend crashes
📉 Partner integrations fail
🔥 Production incidents
😡 Bad user experience

🧩 Traditional Approach (Problem)

Most teams rely on:

Manual reviews ❌
Post-deployment testing ❌
Consumer-driven contract tools (complex setup) ⚠️

👉 These approaches are either slow or unreliable

🚀 Better Approach: OpenAPI Diff

If you are already using OpenAPI/Swagger:

👉 You can compare two API specs

Old version (base)
New version (target)

👉 Detect:

Breaking changes
Non-breaking changes

🛠️ How to Detect API Breaking Changes (Step-by-Step)

Step 1: Get Your OpenAPI Specs

Example:

# base.yaml
paths:
  /user:
    get:
      responses:
        200:
          description: OK

Step 2: Modify API (Simulate Change)

# target.yaml
paths:
  /user:
    get:
      responses:
        200:
          description: OK
          # field removed or changed

Step 3: Compare Specs

Use a CLI tool like SpecShield:

specshield compare base.yaml target.yaml --fail-on-breaking

Step 4: Detect Issues

Output:

❌ Breaking Change Detected:
- Response schema changed for /user

⚡ Automate in CI/CD

You can integrate this into your pipeline:

Example: GitHub Actions

- name: Detect API Breaking Changes
  run: specshield compare base.yaml target.yaml --fail-on-breaking

👉 If breaking change detected → build fails

🔥 Why Use SpecShield?

SpecShield is a CLI tool designed specifically for OpenAPI-based API validation.

Key Benefits:

🚀 Simple CLI (no complex setup)
🔍 Detect breaking changes instantly
⚡ CI/CD friendly
🧩 Works with OpenAPI/Swagger
🔄 Lightweight alternative to Pact

⚔️ SpecShield vs Pact

Feature	SpecShield	Pact
Setup	Simple CLI	Complex
Focus	OpenAPI diff	Consumer contracts
Speed	Fast	Moderate
Use case	API schema validation	Consumer testing

👉 If you use OpenAPI → SpecShield is faster and simpler

🎯 Best Practices

Always version your API
Never deploy without diff check
Automate in CI/CD
Monitor breaking changes

🧠 Final Thoughts

API breaking changes are one of the most common causes of production issues.

👉 The solution is simple:

Use OpenAPI
Compare versions
Automate detection

🚀 Get Started

Install SpecShield:

npm install -g specshield

Run your first check:

specshield compare base.yaml target.yaml --fail-on-breaking

🔗 Learn More

Visit: https://specshield.io

💬 Conclusion

If you're serious about API reliability, detecting breaking changes should be part of your workflow.

👉 Start small
👉 Automate early
👉 Prevent production failures

Happy coding 🚀