Versioning and deprecation
Every public Platform format carries an explicit version. A component rejects an unsupported version before it changes stored data or target state.
Versioned surfaces
| Surface | Version location | Rejection behavior |
|---|---|---|
| YAML manifests | Top-level schema and version fields | Decoding stops before the document is used. |
| HTTP API | URL prefix such as /api/v0/ | An unknown route returns 404. An invalid body returns 400. |
| Runner control messages | protocol_version in each CBOR message | The runner rejects the message before changing state. |
| OCI artifact types | Version in the complete media type | Consumers reject an unsupported media type. |
An error includes the version that was received and the versions that the component accepts. No component silently treats one version as another.
Compatibility rules
An optional field may be added without changing the version when its default is documented and it does not change the meaning of existing documents.
The following changes require a new version:
- Removing a field.
- Changing the type or meaning of a field.
- Making an optional field required.
- Adding a field to a format that rejects unknown fields.
The space.run and
space.capability schemas reject fields they do not
declare. This prevents an old reader from ignoring a resource assignment or
permission that it does not understand.
Deprecation window
The release notes announce a deprecated version and name its replacement. The old version continues to work for the next release and for at least 90 days. Both conditions must be met before removal.
After that window, the normal rejection path names the removed version and its replacement. A migration of stored data is idempotent and resumes safely after interruption.
Current deprecations
There are no announced deprecations.
| Deprecated version | Announced | Replacement | Earliest removal |
|---|
