Versioning and deprecation
Two things carry a version, and they move independently of the obserae release number. Pin your connector to a contract version, never to a release — a connector that declares “built for obserae 0.34” is wrong within a quarter, and wrong in a way nobody notices until a playbook breaks.
The alert contract
| Change | Breaking? | What happens |
|---|---|---|
| A field is added | no | No bump. Your parser must ignore unknown fields — this is the common case, and it happens between minor releases. |
| A field’s meaning is refined without changing its type or name | no | No bump. |
| A field is removed | yes | Major bump. |
| A field’s type changes | yes | Major bump. |
The version is in the document (schema_version) and in the
X-Obserae-Schema header, so you can branch without parsing the body.
Two major versions are supported in parallel for at least two obserae minor
releases. In practice: v1 outputs still exist and still receive byte-identical
v1 payloads today, years after v2 shipped — nothing was migrated under anyone’s
feet. payload_version is a per-output setting, so you migrate one destination
at a time, with a before/after preview, and roll back by flipping it again.
Deprecation, when it comes, is announced in this order: the changelog entry that ships the successor, a banner on affected outputs in the GUI, then removal no sooner than two minor releases later.
The SOAR profile
openapi-soar.yaml is versioned by its info.version. Adding an operation to
the profile is additive. Removing one, or narrowing a response schema, is a
breaking change to every generated connector, and is treated as one.
Declare in your connector’s metadata which two it was built against:
obserae_alert_schema: "obserae.alert/2"
obserae_soar_profile: "1.0.0"
That pair is what a support engineer needs to reproduce your problem. An obserae version number tells them nothing they can act on.