{"slug": "optic-is-dead-a-2026-migration-guide-for-openapi-breaking-changes", "title": "Optic is dead. A 2026 migration guide for OpenAPI breaking changes", "summary": "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.", "body_md": "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.\n\nTL;DR\n\n- Optic's GitHub repo was\narchived on January 12, 2026. Last release:v1.0.9 in August 2025. The`useoptic.com`\n\ndomain no longer resolves.- Optic was acquired by\nAtlassian in April 2024but was never folded into Atlassian Compass.- The MIT-licensed source is still on GitHub, but\nabandoned— 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\nspec-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\nOpenAPI 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.\n\n## What actually happened to Optic\n\nFor 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.\n\nHere's the timeline of how it ended:\n\n| Date | Event |\n|---|---|\nApril 2024 |\nAtlassian acquires Optic Labs. Optic team joins Atlassian. |\nApril 2024 – August 2025 |\nRelease cadence slows. Most commits become dependency bumps. Issues pile up unanswered. |\nAugust 10, 2025 |\nFinal release: v1.0.9. No release notes hint that it's the last. |\nAugust 2025 – January 2026 |\nSilence. No releases, no maintainer responses. The community asks \"is Optic still maintained?\" — no official answer. |\nJanuary 12, 2026 |\nThe `opticdev/optic` GitHub repo is archived (made read-only). The `useoptic.com` domain stops resolving shortly after. |\n\nThere was no formal sunset announcement, no migration guide from the Optic team, no archived-but-here's-a-fork blessing. It just stopped.\n\nThe 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.\n\nThe 1.5k-star repo has 92 forks, but **no fork has emerged as a community successor**. If you keep depending on `@useoptic/optic`\n\nfrom npm, you're depending on unmaintained code that will eventually break when its TypeScript / Node / npm peer dependencies hit EOL.\n\nYou need to migrate. The good news: this is a four-hour job for most teams, not a four-week project.\n\n## What you actually used Optic for (and what you'll need to replace)\n\nOptic 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.\n\n### 1. Spec-to-spec diffing and breaking-change detection\n\nThe most common use case. You had `openapi.yaml`\n\nin your repo, you ran `optic diff`\n\nin CI on every PR, and the action commented on the PR with breaking-change warnings.\n\n**Replacement difficulty:** Easy. Multiple drop-in alternatives exist.\n\n### 2. OpenAPI rule-based linting\n\nOptic had its own ruleset format (`.optic.dev.yml`\n\n) for things like \"all paths must be kebab-case\" or \"every endpoint needs a description\".\n\n**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.\n\n### 3. OpenAPI generation from captured traffic (`optic capture`\n\n)\n\nThis 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.\n\n**Replacement difficulty:** Hard. There is no direct open-source replacement with the same maturity. Alternatives include:\n\n-\n[Pollyjs](https://netflix.github.io/pollyjs/)(record/replay HTTP, generic) -\n[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)\n\nIf you relied heavily on `optic capture`\n\n, your migration is more painful than spec-diff users. Plan accordingly.\n\n### 4. CI integration via GitHub Action\n\nThe `useoptic/optic-action`\n\nGitHub Action posted PR comments with diff results.\n\n**Replacement difficulty:** Easy. Several drop-in alternatives exist with similar or better PR comment design.\n\n### 5. Hosted UI for browsing diffs and history\n\nOptic Cloud (the SaaS layer) gave you a web UI to browse diffs across releases and share them with non-developer stakeholders.\n\n**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.\n\n## Your migration options at a glance\n\nHonest comparison of the realistic alternatives, as of May 2026:\n\n| Tool | What it replaces | Pricing | Hosted UI | OSS engine | PR comments | Active development |\n|---|---|---|---|---|---|---|\n|\nOptic'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 |\n|\nSpec-diff and breaking-change detection (CLI only) | Free / OSS (Apache 2.0) | ❌ No | ✅ Yes (Go) | ✅ Via official GitHub Action | ✅ Active |\n|\nOptic's linting (not diffing) | Free / OSS (Apache 2.0) | ❌ No | ✅ Yes (TS) | Via custom integration | Active but slower post-SmartBear acquisition |\n|\nHosted docs + changelog (a different workflow than Optic's CI flow) | From $50/mo | ✅ Yes | ❌ No | ❌ No native PR comments | ✅ Active |\n|\nLinting + diff (basic) | Free CLI; paid platform | ✅ Yes (paid) | Partial OSS | Via custom integration | ✅ Active |\n\nThree patterns will cover ~95% of Optic migrations:\n\n-\n**You used Optic for spec-diff in CI + you want a UI**→** SpecShield**(most direct replacement, smallest mental model shift) -\n**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) -\n**You used Optic for linting**→** Spectral**(regardless of which diff tool you pick)\n\nThe 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.\n\n## Why SpecShield is the most direct replacement for Optic users\n\nI built SpecShield specifically for the spec-first, CI-driven workflow Optic championed. The mental model is identical:\n\n- You commit your OpenAPI spec to git\n- On every PR, the new spec is compared to the base branch\n- Breaking changes are flagged before merge\n- You get a beautiful diff report (in the UI, the CLI,\n*and*as a PR comment)\n\nWhat's the same as Optic:\n\n- OpenAPI 3.0 and 3.1 support\n- Multi-file spec support (with\n`$ref`\n\n) - Breaking-change classification (removed paths, type changes, new required fields, etc.)\n- CI/CD integration via GitHub App and (soon) free GitHub Action\n- CLI distributed via npm (\n`npx specshield compare ...`\n\n)\n\nWhat's better than Optic:\n\n-\n**Bi-Directional Contract Testing (BDCT)**— verify provider/consumer compatibility, with a`can-i-deploy`\n\ngate. Optic never had this. -\n**Compatibility matrix** for multi-service architectures -\n**Beautiful, screenshot-worthy PR comments**(Optic's were utilitarian) -\n**Active development**— we ship roughly weekly -\n**Free tier** with no time limit (Optic Cloud's free tier was always limited)\n\nWhat's different (some teams will see these as downgrades):\n\n- SpecShield is a SaaS product with a free tier. Optic was BYO-infrastructure if you stayed on the open-source CLI.\n- The core diff engine isn't open-source today (the free GitHub Action will be, when it ships later in 2026).\n- We're a smaller team than Optic was at its peak — though we ship faster.\n\nIf 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.\n\n## Step-by-step migration: Optic → SpecShield\n\nHere'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.\n\n### Step 0 — Audit what you're currently using\n\nBefore deleting anything, find every place Optic is referenced in your repo:\n\n```\n# Find Optic config files\nfind . -name \".optic.dev.yml\" -o -name \"optic.yml\" -o -name \".optic*\"\n\n# Find Optic CI workflows\ngrep -rE \"useoptic/optic-action|optic diff|optic lint\" .github/\n\n# Find Optic CLI invocations in scripts\ngrep -rE \"@useoptic/optic|optic capture|optic verify\" package.json scripts/\n\n# Find references in docs\ngrep -ri \"optic\" README.md docs/ 2>/dev/null\n```\n\nMake a checklist of every file you found. You'll touch each one.\n\n### Step 1 — Install the SpecShield CLI\n\nThe SpecShield CLI is published to npm as `specshield`\n\n. You don't need to globally install it — `npx`\n\nis fine for CI:\n\n```\n# Test it locally — no signup needed for the diff command\nnpx specshield compare old-openapi.yaml new-openapi.yaml\n```\n\nYou'll see output that includes the same categories Optic produced (breaking, non-breaking, additions), formatted as a clean terminal table.\n\nIf you want JSON output for CI scripting, use the `--json`\n\nflag (with `--output`\n\nto also write to a file):\n\n```\n# Print JSON to stdout AND save to a file\nnpx specshield compare old.yaml new.yaml --json --output diff.json\n```\n\nThe JSON shape is:\n\n```\n{\n  \"summary\": { \"breaking\": 3, \"additions\": 12, \"modifications\": 7, \"warnings\": 0 },\n  \"breakingChanges\": [...],\n  \"additions\": [...],\n  \"modifications\": [...],\n  \"warnings\": [...]\n}\n```\n\n### Step 2 — Replace your Optic GitHub workflow\n\nIf you had something like this `.github/workflows/api-check.yml`\n\n:\n\n```\n# OLD — Optic workflow\nname: API contract check\non: [pull_request]\njobs:\n  check:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n      - uses: useoptic/optic-action@v1\n        with:\n          spec: openapi.yaml\n          base_ref: ${{ github.event.pull_request.base.ref }}\n```\n\nReplace it with this:\n\n```\n# NEW — SpecShield CLI workflow\nname: API contract check\non: [pull_request]\njobs:\n  check:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n\n      - name: Extract base spec from base branch\n        run: git show origin/${{ github.event.pull_request.base.ref }}:openapi.yaml > /tmp/base.yaml\n\n      - name: Compare specs\n        id: compare\n        continue-on-error: true\n        run: |\n          {\n            echo '## 🛡️ SpecShield · API contract check'\n            echo ''\n            echo '```\n{% endraw %}\n'\n            npx specshield compare /tmp/base.yaml openapi.yaml --fail-on-breaking\n            echo '\n{% raw %}\n```'\n          } > /tmp/comment.md\n\n      - name: Comment on PR\n        if: always()\n        uses: marocchino/sticky-pull-request-comment@v2\n        with:\n          path: /tmp/comment.md\n\n      - name: Fail the build if breaking changes were found\n        if: steps.compare.outcome == 'failure'\n        run: exit 1\n```\n\nA few notes on this pattern:\n\n- 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.\n-\n`continue-on-error: true`\n\non 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. -\n`marocchino/sticky-pull-request-comment`\n\nupdates 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.\n\n### Step 3 — Migrate your custom rules (if you had any)\n\nThis is the step that takes the longest if you'd customized Optic's rule engine. Optic rules looked like this:\n\n```\n# OLD — .optic.dev.yml\nruleset:\n  - breaking-changes\n  - examples\n  - name: kebab-case-paths\n    where:\n      operation: { in: any }\n    rule:\n      after: must\n      assert: |\n        operation.path.split('/').every(s => /^[a-z0-9-]*$/.test(s))\n```\n\nSpecShield doesn't currently expose a Spectral-compatible custom rule API. For now:\n\n-\n**Breaking-change rules**: covered by SpecShield's built-in detector — no migration needed -\n**Style/lint rules**(kebab-case paths, required descriptions, etc.): migrate these to a separate Spectral step in your CI:\n\n```\n- name: OpenAPI lint\n  run: npx @stoplight/spectral-cli lint openapi.yaml --ruleset .spectral.yaml\n```\n\nWith a `.spectral.yaml`\n\nlike:\n\n```\nextends: spectral:oas\nrules:\n  paths-kebab-case:\n    description: Paths should be kebab-case\n    given: $.paths.*~\n    severity: warn\n    then:\n      function: pattern\n      functionOptions:\n        match: ^(\\/[a-z0-9-]*)+$\n```\n\nWe're working on first-class custom-rule support in SpecShield. Until then, the two-step approach above is the cleanest path.\n\n### Step 4 — Remove Optic dependencies\n\nOnce your new workflow is green:\n\n```\n# Remove npm dep\nnpm uninstall @useoptic/optic\n\n# Remove config\nrm .optic.dev.yml\n\n# Remove the old workflow (or just edit it)\nrm .github/workflows/optic-check.yml\n```\n\nCommit the migration as a single PR — easier to review, easier to revert if anything's off.\n\n### Step 5 — Set up the dashboard (optional but recommended)\n\nIf you want history, team collaboration, BDCT, and a `can-i-deploy`\n\ngate beyond the per-PR diff:\n\n- Sign up free at\n[specshield.io](https://specshield.io) - Install the SpecShield GitHub App on your repo\n- Your existing CLI runs will automatically appear in your dashboard's compare history\n\nNo re-configuration needed — the GitHub App and CLI write to the same backend.\n\n## What SpecShield does NOT replace from Optic (being honest)\n\nThree Optic capabilities don't have a clean SpecShield replacement today. If you depended on these, you need a plan.\n\n### 1. `optic capture`\n\n— generating specs from traffic\n\n**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`\n\nwas central to your workflow, evaluate:\n\n- Continuing to use Optic's archived\n`capture`\n\ncommand standalone (it'll keep working for a while — it's not network-dependent) - Replacing with\n[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)\n\n`optic capture`\n\n-style functionality is on our roadmap but isn't shipping in 2026.\n\n### 2. The MIT-licensed core\n\nOptic'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.\n\nIf \"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.\n\n### 3. The exact ruleset format\n\nOptic's rule DSL is unique. Your rules don't port 1:1 to anything. You'll re-author them in either:\n\n- SpecShield's built-in rules (which cover ~80% of the common cases by default)\n- Spectral's rule DSL (for the remaining 20% of custom style rules)\n\nPlan ~1 hour per custom rule for the rewrite.\n\n## When SpecShield is NOT the right migration target\n\nHonest recommendations for the cases where another tool is better:\n\n| Your situation | Recommended migration target |\n|---|---|\n| \"I just want a CLI that does breaking-change detection, no SaaS\" |\noasdiff. It will outlive every SaaS in this list. |\n| \"We had thousands of dollars of Optic Cloud customization and need a high-touch enterprise vendor\" |\nBump.sh or Stoplight for documentation |\n| \"We need OpenAPI capture from traffic\" | Stay on Optic's archived CLI for now; Speakeasy if you can shift to spec-first |\n| \"We need OpenAPI linting and nothing else\" |\nSpectral (standalone, free) |\n| \"We want a fully self-hosted option with no cloud component\" |\noasdiff + Spectral, both run on your own infra |\n| \"We're a microservice org with consumer/provider contracts\" |\nSpecShield (has BDCT built in) or PactFlow (the dedicated Pact-broker SaaS) |\n\nThe 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.\n\n## What we learned from Optic's end\n\nA few takeaways worth sitting with, especially if you build or pay for developer tools:\n\n**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.\n\n## Migrate today, not next quarter\n\nThree reasons to do this migration *now*, not after your next release:\n\n**Optic's npm package will eventually break.**`@useoptic/optic`\n\ndepends 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.\n\n## Try SpecShield in 5 minutes\n\nIf you've read this far and want to try SpecShield as your Optic replacement:\n\n```\n# No signup needed for the CLI diff command\nnpx specshield compare old-openapi.yaml new-openapi.yaml\n```\n\nFor 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).\n\nFor 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.\n\n*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.*\n\n*Have feedback or corrections? Drop a comment below or email me directly. I'd rather get this right than get this fast.*", "url": "https://wpnews.pro/news/optic-is-dead-a-2026-migration-guide-for-openapi-breaking-changes", "canonical_source": "https://dev.to/deepak_satyam_f22f6f8183f/optic-is-dead-a-2026-migration-guide-for-openapi-breaking-changes-4go2", "published_at": "2026-05-23 18:29:19+00:00", "updated_at": "2026-05-23 18:31:04.940134+00:00", "lang": "en", "topics": ["open-source", "developer-tools", "enterprise-software", "products", "startups"], "entities": ["Optic", "SpecShield", "Atlassian", "Atlassian Compass", "oasdiff", "GitHub", "OpenAPI"], "alternates": {"html": "https://wpnews.pro/news/optic-is-dead-a-2026-migration-guide-for-openapi-breaking-changes", "markdown": "https://wpnews.pro/news/optic-is-dead-a-2026-migration-guide-for-openapi-breaking-changes.md", "text": "https://wpnews.pro/news/optic-is-dead-a-2026-migration-guide-for-openapi-breaking-changes.txt", "jsonld": "https://wpnews.pro/news/optic-is-dead-a-2026-migration-guide-for-openapi-breaking-changes.jsonld"}}