Compatibility Policy
Backward-compatible growth is allowed. Silent breaking changes are not.
This page defines the stability boundary for CLARIXO integrations: what is stable, what may grow additively, what counts as a breaking change, and how degraded compatibility should be handled honestly.
Stable Surface
Required fields should remain stable across non-breaking updates
Backward compatibility
CLARIXO should preserve existing required request and response fields across non-breaking updates.
Additive fields
New optional fields may be added without forcing client rewrites, as long as existing required fields keep their meaning.
Unknown optional fields
Clients should ignore unknown optional fields unless they explicitly support them.
Breaking Change Boundary
These changes require an explicit migration path or version bump
Removed required field
Removing a required request or response field is a breaking change.
Changed required type
Changing the type of a required field is a breaking change.
Changed reserved meaning
Changing the semantic meaning of a reserved field is a breaking change even if the name remains the same.
Reserved Namespaces
Host systems may extend, but they must not overwrite CLARIXO-reserved meaning
Reserved fields
Host systems must not overwrite CLARIXO-reserved fields after normalization.
Host extensions
Host-specific additions should live in a separate namespace or clearly isolated local UX layer.
Rendering freedom
Hosts may render local UI variations, but they must not relabel degraded or structured failure states as healthy success.
Degraded Compatibility
Degraded mode is allowed only when structural honesty is preserved
Allowed degraded mode
If a host cannot provide full observability or full routing context, it may continue in degraded mode.
Required honesty
A degraded success must remain explicitly degraded and must not be flattened into healthy success.
Failure discipline
Structured failures must remain explicit. Do not collapse protocol failures into empty replies or fake success states.