Reference implementations

Implementations

Three reference implementations for producing and validating ChangeSpec events. All are thin, MIT licensed, and cover the same surface area: event construction, JSON Schema validation, Ed25519 signing and verification.

Status

Reference implementations are in active development. The Go library is furthest along. TypeScript and Python follow the same interface design. Pre-release builds available on each repository's develop branch.

  • Go 1.22+

    changespec/changespec-go

    Idiomatic Go library for constructing, validating, signing, and verifying ChangeSpec events. No external dependencies beyond the Go standard library for core functionality. JSON Schema validation uses santhosh-tekuri/jsonschema.

    Install
    go get github.com/changespec/changespec-go
    Produce an event
    import "github.com/changespec/changespec-go/event"

e := event.New("anthropic", event.CategoryAPIDeprecation, event.SeverityMedium)
e.Title = "claude-2 model deprecated, sunset 2027-01-01"
e.Summary = "The claude-2 and claude-2.1 model identifiers are deprecated..."
e.SunsetDate = "2027-01-01"
e.ActionRequired = true

if err := e.Validate(); err != nil {
    log.Fatal(err)
}

json, _ := e.Marshal()
  • TypeScript Node 18+

    changespec/changespec-ts

    TypeScript library with full type coverage for all ChangeSpec fields. Exports ESM and CJS. Includes Zod schemas for runtime validation. Ed25519 signing uses Node.js built-in crypto module.

    Install
    npm install @changespec/sdk
    Produce an event
    import { createEvent, Category, Severity } from '@changespec/sdk'

const event = createEvent({
  vendor_id: 'anthropic',
  category: Category.APIDeprecation,
  severity: Severity.Medium,
  title: 'claude-2 model deprecated, sunset 2027-01-01',
  summary: 'The claude-2 and claude-2.1 model identifiers are deprecated...',
  sunset_date: '2027-01-01',
  action_required: true,
})

const validated = await event.validate()
const json = JSON.stringify(validated)
  • Python 3.11+

    changespec/changespec-py

    Python library using Pydantic v2 for event construction and validation. Ed25519 signing uses the cryptography package. Supports both sync and async usage patterns.

    Install
    pip install changespec
    Produce an event
    from changespec import Event, Category, Severity

event = Event(
    vendor_id="anthropic",
    category=Category.API_DEPRECATION,
    severity=Severity.MEDIUM,
    title="claude-2 model deprecated, sunset 2027-01-01",
    summary="The claude-2 and claude-2.1 model identifiers are deprecated...",
    sunset_date="2027-01-01",
    action_required=True,
)

event.validate()  # raises ValidationError if invalid
json_str = event.model_dump_json()

JSON Schema

The normative JSON Schema for ChangeSpec 1.1 is maintained in the spec repository and can be used directly for validation in any language.

Schema URL
https://changespec.com/schema/v1.1/schema.json
Validate with ajv (Node.js)
import Ajv from 'ajv'
import addFormats from 'ajv-formats'
import schema from 'https://changespec.com/schema/v1.1/schema.json' assert { type: 'json' }

const ajv = new Ajv()
addFormats(ajv)
const validate = ajv.compile(schema)
const valid = validate(event)

Contributing an implementation

Implementations in other languages are welcome. To add a community implementation to this page, open an issue on the spec repository with:

  • Language and minimum runtime version
  • GitHub repository link
  • Package registry link (npm, PyPI, crates.io, etc.)
  • Confirmation that the implementation passes the ChangeSpec conformance test suite

The conformance test suite is published at github.com/changespec/spec/tests.