Versioning
Every format the Platform exchanges across a process, a network, or a release carries an explicit version, and each reader speaks one version of it. Readers differ in whether they check that version and in what they do with another.
Versioned formats
| Format | Where the version lives | Current version | What a reader does with another |
|---|---|---|---|
| YAML documents | Top-level schema and version members, both required | "1" | space.app, space.target, and space.target-profile refuse another version while decoding, naming it. space.project requires the member and does not check its value. Every document refuses a member its schema does not declare. |
| HTTP API | Path prefix | /api/v0/ | An unknown route answers 404. A malformed body, or one carrying an undeclared member, answers 400. Refusals are problem documents. |
| Runner control protocol | First item of every CBOR frame | 8 | A frame at another version is refused as a version mismatch, naming both versions, before its payload is read. |
| OCI media types | The media type string of each descriptor | Varies by type | A consumer compares the complete media type and refuses anything else. Some types carry a version, such as application/vnd.spaceos.build.v1, and others do not, such as application/vnd.spaceos.capability+json. |
The runner is the daemon on a node that launches and supervises workloads. The CLI uses the control protocol to drive the runner and a ground. Each control message is one CBOR frame, and the frame is an array of two items. The first item is the protocol version, as an unsigned integer. The second item is the command or the response.
The CLI and the node ship in one release, so both ends speak the same version. When they differ, the CLI changes nothing on the peer and leaves it running. It says which end is older and prints the command that replaces the runner or the ground with one at the CLI's version. The other way out is a CLI at the peer's version.
An OCI image is a manifest that lists content-addressed blobs. Each reference to a blob is a descriptor that carries the blob's SHA-256 digest, its size, and a media type string that says how to parse the bytes.
Schema changes
A reader decodes one shape per format. No release ships two decoders for one format, and none migrates a document from an older version.
These additions keep the version:
- a new optional member with a stated default;
- a new route;
- a new media type.
These changes take a new version:
- removing a member;
- changing a member's type or meaning;
- making an optional member required;
- adding a required member.
The release that introduces a new version removes the decoder for the old one.
Renamed commands
A command spelling that has moved is refused, and the refusal names the spelling that replaced it.
