mirror of https://github.com/garrytan/gstack.git
33 lines
1.4 KiB
Markdown
33 lines
1.4 KiB
Markdown
# Schema Compatibility
|
|
|
|
gstack uses JSON Schema definitions in `schemas/` for cross-runtime file formats
|
|
(dispatch, completion, handoff, activity). Both the gstack dispatch daemon and
|
|
OpenClaw bridge skill validate against these schemas.
|
|
|
|
## Version policy
|
|
|
|
Schema version is tied to gstack's `VERSION` file.
|
|
|
|
### Breaking change (major version bump required)
|
|
|
|
A change is **breaking** if it:
|
|
- Removes a required field
|
|
- Changes a field's type (e.g., string to integer)
|
|
- Changes the semantics of an existing field (e.g., `duration` from milliseconds to seconds)
|
|
- Narrows an enum (removes a valid value)
|
|
|
|
### Non-breaking change (minor version bump)
|
|
|
|
A change is **non-breaking** if it:
|
|
- Adds a new optional field
|
|
- Widens an enum (adds a new valid value)
|
|
- Relaxes a constraint (e.g., increases maxLength)
|
|
- Adds a new schema file
|
|
|
|
### Rules
|
|
|
|
1. **Additive by default.** New fields are always optional. Existing readers ignore unknown fields.
|
|
2. **Breaking changes require a major version bump** and must be called out in CHANGELOG.
|
|
3. **Both sides validate.** The gstack daemon validates incoming dispatch files. The OpenClaw bridge validates completion reports. If validation fails, the file is rejected with an error status, not silently ignored.
|
|
4. **Schema version in file.** Future versions may add a `schema_version` field to each file for explicit version negotiation. For now, schema version is implied by gstack VERSION.
|