Skip to content

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.

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.

Terminal window
# Every version, newest first
curl http://localhost:8080/v1/event-types/order.created/versions
# One version's schema and sample payload
curl http://localhost:8080/v1/event-types/order.created/versions/2

The 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.

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:

Terminal window
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.

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:

Terminal window
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.

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.

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.

  1. Push events from the producer (or with sparrow push). Each unknown name becomes a schema-less event type, and every payload is kept.

  2. 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.

    The Events page: customer.created has a schema and shows Schema; order.placed was auto-registered without one and shows Infer schema.

    An event record’s header with the Use as schema sample and Re-push buttons.

  3. 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.

  4. Generate, review and save. Choose Generate Schema, refine the result in the editor (add enum, pattern, descriptions, tighten required), 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.

    The schema editor after merging five order.placed events: the generated schema on the left, and on the right the ticked events and a coverage table where coupon is string or null, seen in 4 of 5 events, and optional, and customer_email is a string with the email format.

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 null becomes ["string", "null"], and a mix of integers and decimals becomes number.
  • Array items are inferred from every element, not just the first.
  • format is 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.

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.

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.