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

The article announces that Optic, an open-source tool for OpenAPI breaking-change detection, has been abandoned after its GitHub repo was archived in January 2026 and its domain went offline. It provides a migration guide for users, recommending SpecShield or oasdiff as replacements for spec diffing and breaking-change checks, while noting that Optic's unique feature for generating OpenAPI specs from test traffic has no direct replacement. The post also includes a feature comparison table and a step-by-step migration walkthrough, estimating the process takes about four hours for most teams.

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 2024but 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 Web UI + CLI + GitHub App + free GitHub Action or SpecShield open-source CLI, no UI . oasdiff - 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 https://www.atlassian.com/software/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 https://github.com/stoplightio/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 https://netflix.github.io/pollyjs/ record/replay HTTP, generic - Speakeasy https://www.speakeasy.com/docs 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 | |---|---|---|---|---|---|---| | 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 | | Spec-diff and breaking-change detection CLI only | Free / OSS Apache 2.0 | ❌ No | ✅ Yes Go | ✅ Via official GitHub Action | ✅ Active | | Optic's linting not diffing | Free / OSS Apache 2.0 | ❌ No | ✅ Yes TS | Via custom integration | Active but slower post-SmartBear acquisition | | Hosted docs + changelog a different workflow than Optic's CI flow | From $50/mo | ✅ Yes | ❌ No | ❌ No native PR comments | ✅ Active | | 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 https://github.com/oasdiff/oasdiff and Spectral https://meta.stoplight.io/docs/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 https://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 https://netflix.github.io/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 https://specshield.io/signup — no credit card, generous free tier. Pricing details at specshield.io/pricing https://specshield.io/pricing . For migration support, email me at founder@specshield.io mailto: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.