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

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:

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:

Three patterns will cover ~95% of Optic migrations:

1. You used Optic for spec-diff in CI + you want a UI → SpecShield (most direct replacement, smallest mental model shift)
2. 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)
3. 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:

1. Sign up free at specshield.io
2. Install the SpecShield GitHub App on your repo
3. 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:

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:

1. 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.

2. 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.

3. 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.

4. 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:

1. 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.

2. 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.

3. 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.