Versioning & Compatibility
8. Versioning & Compatibility
The API and message format are designed to support forward progress while maintaining compatibility across devices, clients, and middleware components.
Message-Level Versioning
Each message includes a required Version field that indicates the sender’s API protocol version. This allows the backend (W3S) to:
- Validate schema versions precisely
- Apply conditional logic for deprecated or evolving fields
- Maintain compatibility with older devices or clients for a defined support window
Example:
"Version": "1.0"Backend Compatibility Model
- W3S always operates on a single canonical API version.
- It is backward compatible with earlier message versions for a limited period.
- Messages using unsupported or too-old versions will be rejected with a validation error.
Version-specific behavior is handled by:
- Mapping
MessageTypeIdschemas to supported version ranges - Adding or deprecating fields conditionally in the JSON schema
Device & Client Expectations
- All senders (OSS8 or Clients) must include a
Versionfield in every message. - Devices and clients are expected to upgrade their firmware/software if they require support for newly introduced
MessageTypeIds or fields. - When a sender declares a newer version than supported by W3S, it may be rejected or logged depending on configuration.
Notes
-
Versioning applies only to the message schema, not to the WebSocket protocol itself.
-
Semantic versioning (e.g.,
1.2.3) may be supported in the future, but policy decisions are still pending. For now, only the"major"version component will be used to determine compatibility boundaries. A formal policy for versioning, including criteria for triggering major version changes, is yet to be established. -
Breaking changes should result in either:
- A new
MessageTypeIdwith a new schema, or - An incremented major version in the
Versionfield with support logic in W3S
- A new