Event Type Versions
An event type is a contract between the systems that push events and the subscriptions that receive them. Sparrow treats it that way: every schema the type has ever had is kept as a numbered version, each pushed event records the version it was accepted under, and a type is never deleted.
You always refer to an event type by its name. The version is bookkeeping: push, subscriptions and the API resolve the name to the current version.
stateDiagram-v2
accTitle: Lifecycle of an event type
accDescr: Lifecycle of an event type: unregistered, then version 1 (blank if auto-registered, filled in by the first schema without a new version), then version 2 on a compatible schema change, version 3 on a breaking change applied with allow_breaking, then deactivated and reactivated without changing the version.
[*] --> Unregistered
Unregistered --> v1_blank : push, with SPARROW_AUTO_REGISTER_EVENTS on
Unregistered --> v1 : register or import with a schema
v1_blank --> v1 : first schema added (fill-in, stays v1)
v1 --> v2 : compatible schema change
v2 --> v3 : breaking change, applied with allow_breaking
v3 --> v3_inactive : deactivate (active=false, same version)
v3_inactive --> v3 : reactivate
note right of v3 : Every version is kept. Each event records the version it was accepted under. Event types are never deleted.
What creates a new version
Section titled “What creates a new version”Only a change to the schema creates a new version. Everything else changes the current version in place.
| Change | Result |
|---|---|
| The name does not exist yet | created: version 1 |
| A schema is added to a type that had none | updated: version 1 is filled in, and schema_defined_at records when |
| The schema changes (compared by value, so key order and whitespace never count) | new_version: the version number goes up and the previous version is kept |
| The schema is removed | new_version, and it is a breaking change |
Only the description, metadata or active changes |
updated: same version |
| Nothing changes | unchanged: nothing is written |
PATCH /v1/event-types/{name} returns a change object saying which of these
happened, with version, previous_version and the list of changed fields.
flowchart TD
accTitle: Decision flow for saving an event type
accDescr: Decision flow for saving an event type: reserved names are rejected, the current row is locked, a missing type is created at v1, a first schema fills in v1, a changed schema is classified and either refused with 409 when breaking for subscribers or saved as a new version, other changes update in place, and identical definitions write nothing.
A["Register, PATCH, import, or auto-register"] --> R{"name starts with sparrow. ?"}
R -- "yes, from a user" --> RJ["400: reserved for Sparrow's own events"]
R -- no --> L["Lock the current row"]
L --> E{"exists?"}
E -- no --> C["created: v1 + history row"]
E -- yes --> S{"current has no schema,<br>new one has a schema?"}
S -- yes --> F["updated in place:<br>fill in v1, set schema_defined_at"]
S -- no --> D{"schema differs by value?"}
D -- no --> M{"description, metadata<br>or active differ?"}
M -- yes --> U["updated in place, same version"]
M -- no --> N["unchanged: nothing written"]
D -- yes --> K["classify from the subscribers' side"]
K --> B{"breaking, and subscriptions<br>receive this type?"}
B -- "yes, no allow_breaking" --> X["409: nothing written, reasons listed"]
B -- otherwise --> V["new_version: bump, keep old version,<br>regenerate sample payload"]
Every write (register, PATCH, import, and auto-register on push) goes through the same rules, in a transaction that locks the event type’s row, so two concurrent changes can never claim the same version number.
Reading the history
Section titled “Reading the history”# Every version, newest firstcurl http://localhost:8080/v1/event-types/order.created/versions
# One version's schema and sample payloadcurl http://localhost:8080/v1/event-types/order.created/versions/2The event type’s own response carries version, and every pushed event
carries event_version: the version whose schema it was validated against.
A batch re-push keeps the original event’s version.
In the UI, the version in the event list links to the type’s history.
Breaking changes
Section titled “Breaking changes”Before a new version is written, Sparrow compares the old and new schemas from a subscriber’s point of view. The rule is strict: anything that could break a subscription’s payload transformation is breaking, and anything Sparrow cannot prove safe counts as breaking.
| Compatible | Breaking |
|---|---|
| Adding a property, optional or required | Removing a required property |
| Removing an optional property | Making a required property optional |
Narrowing a type (number to integer, or adding a type where there was none) |
A type that admits a new kind of value (string to integer, integer to number, object to array) |
Changing value constraints: enum, minimum, maxLength, pattern, format, … |
Removing the schema |
Any change under oneOf, anyOf, allOf, not, $ref, patternProperties, if/then/else or dependentSchemas |
Nested objects and array items are checked the same way, and every reason
names its path, for example customer.email: removed required property.
A breaking change to an event type that any subscription receives (by
name, or through a catch-all * subscription) is refused with 409 Conflict
and the reasons, and nothing is written. To apply it anyway, say so
explicitly:
curl -X PATCH 'http://localhost:8080/v1/event-types/order.created?allow_breaking=true' \ -H 'Content-Type: application/json' \ -d '{"event_schema": {"type": "object", "properties": {"id": {"type": "string"}}}}'In the UI, saving a breaking change asks you to type the event type’s name. If no subscription receives the type there is nothing to break, so no opt-in is needed; the change is still classified and reported.
When a schema change does reach a subscription whose template no longer fits,
the delivery fails visibly with error category template_error; see
Transforming Payloads.
Retiring an event type
Section titled “Retiring an event type”Event types are never deleted, and there is no delete endpoint. A definition with history cannot be removed at the database level either. To retire one, deactivate it:
curl -X PATCH http://localhost:8080/v1/event-types/order.legacy \ -H 'Content-Type: application/json' -d '{"active": false}'Pushes of an inactive type are rejected with 409. Its versions and past
events are kept, and setting active back to true reactivates it.
Unregistered event names
Section titled “Unregistered event names”By default, pushing an event whose type is not registered fails with 404:
production event types arrive by registering or importing
them. Because event types are never deleted, creating them implicitly would
turn every producer typo into a permanent name.
For local development, set SPARROW_AUTO_REGISTER_EVENTS=true (make run
does) to create a schema-less type on first push instead. The CLI’s
sparrow push registers an unknown type and retries on its own.
Inferring a schema from real events
Section titled “Inferring a schema from real events”The quickest way to get an accurate schema is to let the producer show you what it sends. On a development instance with auto-registration on, push events from the real producer first, then generate the schema from what was stored instead of writing it by hand.
-
Push events from the producer (or with
sparrow push). Each unknown name becomes a schema-less event type, and every payload is kept. -
Open the schema editor. On the Events page, a type without a schema shows Infer schema. From any event record, Use as schema sample opens the editor with that event picked.


-
Pick the samples. The Recent events tab lists the type’s last 20 events across consumers, with the latest one ticked. Tick several, or choose All, to merge them. A coverage table then shows each field’s type, detected format, and how many of the events had it (
4/5), so you can see why a field will come out optional before anything changes. Inside arrays (items[].sku) the count is over array elements, not events. -
Generate, review and save. Choose Generate Schema, refine the result in the editor (add
enum,pattern, descriptions, tightenrequired), and save. Saving goes through the same checks as any other schema change. If the type already has a schema, you are asked before it is replaced.
When merging events:
- A property is required only if every event had it. One that is missing from some events becomes optional.
- Types seen across events are combined: a field that is sometimes
nullbecomes["string", "null"], and a mix of integers and decimals becomesnumber. - Array items are inferred from every element, not just the first.
formatis set (uuid,date-time,date,email,uri,ipv4) only when every sampled value at that position matches it, using strict patterns. Formats also make the generated sample payload, used by template previews and AI drafting, more realistic.- Only structure goes into the schema, never values from the payloads.
Paste a payload in the Paste tab to generate a schema without any stored events.
Naming rules
Section titled “Naming rules”A new event type name is made of dot-separated parts of lowercase letters,
digits, _ and -: order.created, stripe.payment_intent.succeeded,
invoice.sent.v2. At most 255 characters. Spaces, capitals, empty parts
(order..created, a leading or trailing dot) and other punctuation are
rejected with 400, whether the name is registered, imported or
auto-registered on push. Because event types are never deleted, the rule
stops a typo from becoming a permanent name.
The rule applies when a type is created. An event type saved before it existed keeps working: it can still be pushed, updated and exported.
Reserved names
Section titled “Reserved names”Names starting with sparrow. (in any case) belong to Sparrow’s own system
events, such as sparrow.webhook.health_changed. You can subscribe to them
only under the _sparrow consumer (see
Webhook Health Alerts), and you
cannot register, change, import, export or push them.
GET /v1/event-types?consumer=<name> lists only the event types that consumer
can subscribe to.