Versioning
Version handling is specific to each format. Do not assume that all Platform formats use the same compatibility rule.
Current behavior
| Surface | Version location | Current behavior |
|---|---|---|
| YAML manifests | Top-level schema and version fields | The decoder requires both fields. It validates the schema name and rejects undeclared fields. The common manifest codecs currently store version as a string but do not restrict its value. |
| Integration HTTP API | /api/v0/ path prefix | The routes this product offers to callers outside it use /api/v0/. A path with no matching route returns 404. |
| Runner control protocol | First item in each CBOR command or response frame | The current protocol version is 3. A frame with another version is rejected before its payload is returned to the caller. |
| OCI artifacts | Complete artifact or media type | Consumers compare the complete type. Some SpaceOS types include a version, such as application/vnd.spaceos.build.v1. Other current types, such as application/vnd.spaceos.capability+json, do not. |
The version field in a YAML manifest is required metadata. It is not currently
a compatibility check. A caller must not use it as evidence that a manifest is
supported.
Schema changes
The current source supports one shape for each public schema. It does not ship multiple schema decoders or an automatic migration between schema versions.
Adding an optional field with a defined default can keep the current schema version. These changes require a new schema version:
- Removing a field.
- Changing a field’s type or meaning.
- Making an optional field required.
- Adding a required field.
The new version must not be documented as supported until its decoder and rejection tests are available.
Deprecation
A command spelling that has moved refuses by name and prints the spelling that replaced it.
