An open JSON format for API breaking changes, deprecations, and supply-chain retractions.

When a vendor ships a breaking API change, patches a CVE, or retracts a package after a supply-chain compromise, there is no standard format for the notification. ChangeSpec is a JSON event format for API change announcements - designed so developers, automated agents, compliance teams, and the tools they already use can consume the information directly.

ChangeSpec 1.1 is released under Apache 2.0. The format has been security-audited and implemented in Go, TypeScript, and Python. It is stable and ready for production use.

Current release: v1.1 stable  Apache 2.0 License  |  github.com/changespec/spec

How it works

Vendor side

Stripe ships a breaking webhook change. Today: blog post, email, Slack, changelog. Each reaches a different subset of developers. Most miss it.

blog post email slack changelog page nothing
with ChangeSpec, vendor publishes once
The event
application/vnd.changespec+json
{
  "specversion": "1.1",
  "vendor_id":   "stripe",
  "category":    "api_breaking",    // CI can gate deploys on this
  "severity":    "high",            // your alert threshold
  "title":       "charges field removed from PaymentIntent",
  "affected_versions": ">=2024-11-20",  // lockfile scanner uses this
  "migration_hint": "Use paymentIntent.latest_charge instead.",
  "action_required": true           // digest highlights this
}
every tool that speaks the format delivers it
Developer side
IDE / editor

inline warning on the affected import

CI pipeline

deployment gate on api_breaking

AI assistant

reads migration_hint, patches affected code

RSS / digest

weekly summary, critical alerts immediate

Compliance

timestamped audit log for DORA / OSFI

Read the full specification →

Who this is for

The same specification serves three different roles in the change communication chain.

Developer using external APIs

You find out Stripe changed a field when prod breaks at 2am.

You depend on Stripe, Anthropic, Vercel, and 20+ others. Each publishes breaking change notifications in a different format - blog post, email, Slack, nothing. ChangeSpec is a structured event format that IDEs, CI pipelines, and dependency tools can consume to surface relevant changes before they reach production.

Read the specification →
API or SDK vendor

You announce in six channels. Half your users still miss it.

Blog post, changelog, email, Discord, release notes - you publish everywhere and developers still get surprised by breaking changes. Publish one ChangeSpec event per change and every downstream tool that speaks the format delivers it in whatever channel the developer already uses. One publish, full coverage.

How vendors publish →
Security engineer

SLSA attestations passed. The malicious packages still shipped.

Build provenance proves an artifact was built in CI. It cannot prove the CI wasn't compromised. ChangeSpec 1.1's retraction events carry a vendor-signed "do not install" signal - held on keys separate from the build environment. The out-of-band signal that provenance alone cannot provide, with do_not_install, last_known_good_version, and provenance_invalidated fields for automated tooling response.

Retraction specification →

Help improve this specification

Read the specification. Tell us where it is wrong, where it is missing something, or where it would not work at your company. Open an issue. Propose a change. Try to implement it and tell us what broke.

If you work at a company that ships an API, a library, or a SaaS product: we want to know whether you could publish your changes in this format, and what would stop you.

If you build tools that consume vendor changelogs, CVEs, or release notes: we want to know whether this format would make your work easier.

What the ChangeSpec JSON event format defines

A self-describing JSON event for a software change - one event per breaking change, deprecation, CVE, TOS update, retraction, or similar. Each event carries the minimum structured information a consumer needs to decide whether to act: category, severity, affected versions, source, migration guidance, and an optional cryptographic signature from the publisher.

The specification defines: a vendor identifier namespace, transport bindings (webhook, MCP, RSS, polling API), a backward compatibility policy, and a security threat model with Ed25519 signing and key separation requirements.

Read the specification →

ChangeSpec version history and roadmap

ChangeSpec 1.0 launched in April 2026. Version 1.1 added retraction events and the provenance_invalidated field, responding to the wave of supply-chain compromises affecting npm and PyPI ecosystems. Version 1.1 also requires signing keys to be held separately from the CI/CD environment that builds and publishes package artifacts.

The 1.2 roadmap will add key transparency log support and signed sequence numbers. Feedback and implementations are always welcome via GitHub issues.

Reference implementations in Go, TypeScript, and Python

Production-ready reference implementations that parse and validate ChangeSpec events against the v1.1 schema. All three pass the conformance test suite.

Implementation Language Source Registry
changespec-go Go github.com/changespec/changespec-go go get github.com/changespec/changespec-go
changespec-ts TypeScript / Node.js github.com/changespec/changespec-ts npm publish pending
changespec-py Python github.com/changespec/changespec-py PyPI publish pending

Implementation notes →    Related hosted project at changespec.com →