# Versioning

What can change within v1, and how breaking changes are announced.

The major version is in the address: `/v1`. The contract's revision is 1.2.0; it goes up with each published change, and the [changelog](https://docs.kapiworks.com/changelog) lists each one.

## Changes within v1

v1 grows only by adding. It can add paths, operations, fields, values and error codes without notice, so:

* Ignore fields you do not know.
* Fields that list values, such as `outcome`, `status` and `requirement`, are open: new values can appear. Treat an outcome you do not know as needing review, not as completed.
* Handle an error code you do not know by its HTTP status.

## Breaking changes

Removing a path, an operation, a response field or an error code, or making a field required, would break clients. Changes like these come only with a new major version, `/v2`, announced at least 12 months ahead, here and in the changelog.

## Follow changes

* The [changelog](https://docs.kapiworks.com/changelog), also as an [RSS feed](https://docs.kapiworks.com/changelog/rss.xml).
* The contract at [`https://api.kapiworks.com/v1/openapi.json`](https://api.kapiworks.com/v1/openapi.json), to compare one revision with the next.