# Versioning and deprecation policy

## Contract version

The public HTTP contract is rooted at `/api/v1`. Additive, backward-compatible fields and endpoints may be released within v1. Clients must ignore unknown JSON properties and must not depend on property ordering.

A breaking change requires a new URL major version, migration documentation, and a published retirement date for the preceding major version. Decision definitions have their own `decisionVersion`; pin it when reproducibility matters.

## Compatibility commitments

- Existing required request properties are not renamed or removed within v1.
- Existing response properties do not change meaning within v1.
- New optional response fields, enum values, warnings, and discovery records may appear.
- The normative contract is the versioned OpenAPI file in this kit; guides and examples are explanatory.
- `/api/v1/execute-catalog` is compatibility-only. New integrations use `/api/v1/decide`.

## Deprecation communication

Deprecations should be announced through release notes and direct customer notification. A production retirement window and support commitment must be agreed and published before any endpoint is removed. No numeric retirement window is promised by this client kit because none is currently established as a contractual service policy.