Contract evolution

The People’s Court API keeps existing operation IDs and compatible request/response contracts stable. The migration guide records each alias, replacement and capability window. Canonical publication is a preview until its deployment and final verification gates are met.

Additive changes

New optional fields, endpoints and operations are additive only when existing requests and consumers remain valid. Clients should ignore unknown object fields and tolerate documented extensible values; the server must not reinterpret accepted consent, signed artifacts or historical Rules. Adding required input, narrowing authorization, changing response types or removing enum values requires compatibility review, even when the automated breaking checker cannot detect it.

Breaking changes and operation IDs

A breaking contract gets a distinct operation ID and separately published operation/version, its own migration guide and minimum 180-day equivalent-capability window. Do not silently repurpose an existing operation ID, route or SDK method. Removal additionally requires final workflow coverage and migration or an agreed extension for known active callers. Unreplaced capabilities have no running clock. v1 remains frozen.

Webhooks

Version webhook event schemas explicitly in the published contract. Keep existing event IDs, signing inputs, signature verification and replay semantics stable for the subscribed version. A breaking payload is a new schema version with explicit subscriber migration and its own window; do not switch existing subscriptions silently. Callbacks remain at least once: deduplicate by event ID and fetch authoritative state. A callback does not establish payment or override recorded case service.

SDK releases

Use semantic versioning: compatible fixes are patch releases, additive helpers are minor releases, and breaking public method/type changes require a major release with migration notes. Existing unversioned legacy methods keep their v1 semantics; introducing canonical helpers must not retarget them silently. Generated contract changes and handwritten SDK behavior are reviewed together. MCP tool exposure requires its own scope review; generated types do not add tools.

Announcements and gates

Announce changes in the changelog before activating a window, including affected operations, replacement, authentication differences, dates and extension route. Run generation, contract lint and the breaking checker against the PR base; inspect security, response and inline-schema changes beyond that checker’s coverage. Verification follows the repository’s application gate: behavior-capable changes require the full test suite; presentation-only changes use focused checks, TypeScript, build, and browser rendering. Contract changes also require generation and a breaking-change comparison.