Versioning an Approval Schema Without Breaking Queues

A version tag is what turns "which shape is this?" from a guess into a lookup. Store it as an immutable field on the approval record, written once at creation and never updated by edits:

{
  "id": "apr_88213",
  "schema_version": 1,
  "status": "pending",
  "requester": "j.alvarez",
  "amount": 4200,
  "cost_center": null,
  "created_at": "2026-02-11T09:14:00Z"
}

When you introduce the new field (cost_center above), bump to schema_version: 2 for cards created after the change and dual-write: the new field is populated, the old representational fields stay populated too. Cards already in the queue keep schema_version: 1 and remain valid under the version 1 schema file, which you retain alongside version 2 rather than overwrite.

Two rules make this hold:

• The validator is selected by the tag, not by the current deploy. A card at version 1 is validated against the version 1 schema for as long as it exists, even after the code no longer writes that shape.
• Edits do not change the tag. If a reviewer edits a version 1 card, it stays version 1 and simply cannot supply the new field. Only a deliberate migration step (covered below) moves a card forward.

This is the same separation that business process tooling makes between a process definition and a running instance: existing instances continue on their original definition while new instances pick up the latest one, and migration is a deliberate operation rather than a side effect of deployment Camunda versioning guidance, summarized. Approval rules changing mid-flight is not hypothetical; the same source lays out the three explicit treatments for in-flight documents (continue, migrate, withdraw and resubmit) and warns against silently re-routing them.

One useful side effect of the tag: your approval-time metric becomes sliceable by version. If cycle time jumps the week version 2 ships, you can tell whether the new field slowed reviewers down or whether the queue simply got longer, which is the kind of distinction approval-time reporting is meant to surface the Atlassian approval-time discussion.

The reviewer UI is where schema changes actually strand work, because a reviewer looking at ten queued cards does not care which version each one is. The fix is a reader registry: a small map from version number to a render function, with a single dispatcher in front of it.

const readers = {
  1: renderCardV1,   // no cost_center field
  2: renderCardV2,   // cost_center present and shown
};

function renderCard(card) {
  const reader = readers[card.schema_version] ?? readers[highestSupportedVersion()];
  return reader(card);
}

Three details matter more than the code itself:

• The fallback is explicit and logged. If an unknown version arrives (a client cached an old bundle, or a producer shipped ahead of consumers), render with the highest supported reader and emit a counter. Silent fallbacks hide the exact drift you are trying to detect.
• The new reader degrades gracefully on old cards. renderCardV2 should display "not provided" rather than an empty box or a validation error when cost_center is missing, so a reviewer can still approve a version 1 card correctly.
• The dispatcher is the only place that branches on version. Scattering if (version === 2) through components is how you get a UI that half-renders the new shape.

This mirrors the guidance that consumers should be upgraded before producers for backward-compatible changes Data Expert's compatibility guide: ship the UI that can read both shapes first, then start writing the new shape, then worry about enforcement. Retool's guardrail write-up makes the same point at a higher level, noting that agents which can take real actions need layered validation and human oversight rather than a single check Retool on AI guardrails, and the human-in-the-loop queue design described for service desks is the same loop you are versioning Autommate's review queue guide.

Backfilling means writing the new field onto cards that already exist. Do it in bounded batches with a dry run first, and never touch the decision history. Approval workflows depend on traceability of who approved what and why, so the backfill must add data rather than rewrite it StackAI's approval workflow design.

A workable sequence:

1. Measure the gap. Count open cards by schema_version where the new field is null. That number is your compatibility window in units of work, not days.
2. Dry run on a sample. Take 100 cards, derive the field from existing data if you can (for example, map an existing free-text department string to cost_center), and check how many resolve cleanly.
3. Batch the write. Update in chunks, keyed by card ID, with the version bump applied in the same transaction. Log the before and after value per card.
4. Re-run the gap count. Repeat until zero.
5. Freeze writes for the last batch only. Cards created during the backfill already carry the field through dual-write, so the only risk is a card edited mid-batch; a short write lock on the batch range closes it.

Worked example. Suppose 3,400 approvals are open, 2,100 of them at version 1. A nightly batch of 300 cards takes seven nights at roughly 15 percent of the queue per pass. If each pass derives cost_center correctly for 92 percent of cards and flags the rest for reviewer input, you need a small reviewer task for about 168 cards, which is far cheaper than blocking the queue for a week while every card is rewritten by hand. Compare that against the alternative of forcing the field immediately: all 2,100 version 1 cards fail validation on the next save, and the queue stops.

The reversibility test from technology planning applies directly: a backfill you can rerun is a two-way door, while a schema flip that invalidates data is closer to a one-way door, so plan the batch process before you need the escape hatch PTG on reversible decisions. The same discipline that firewall change management applies to rollback plans (write the rollback before approval, not after the outage) applies to your backfill script the firewall change management guide.

The field becomes required only when two independent conditions hold, and both should be checked automatically rather than asserted in a meeting:

Only then change the schema: remove the field from the nullable path, add it to required, and retire the version 1 reader from the registry (keep the file for archival validation). If you want a softer landing, keep the field optional in the stored schema and enforce it in the write path for new cards only, which is exactly what conditional keywords like dependentRequired are built for the JSON Schema reference. Many teams never flip required at all; they enforce at creation time and let the historical cards stay as they are, which is a legitimate end state.

Two failure modes to plan against. First, agents and automation writing into the approval system can produce version 1 cards long after humans stopped, so check the producer list, not just the UI. Second, mobile or embedded reviewer clients update on their own schedule; counting sessions rather than installs is the honest measure, and the same "old client, old schema" problem is called out as a standard feature of schema evolution ByteByteGo on schema evolution and Simon Späti's notes on the same.

If the queue is fed by an AI agent that drafts or triages approvals, the schema change is also a guardrail change: the agent's output must validate against whichever version it is writing, and anything it cannot populate should escalate rather than guess Sweet Security's guardrail taxonomy, Aembit on runtime controls, Salesforce's guardrail guide. Note how ITIL-style change classification maps onto your schema edits: an additive optional field is a standard change, a new required field is a normal change with approval, and a coordinated cutover across validators, UI and producers is closer to a major change Virima's ITIL change types.

When the next schema revision touches several model outputs at once (a triage label, an amount extract, a risk score), routing all of those calls through one endpoint keeps the version contract in one place; Quanta Inference exposes text, image, video, audio and embedding models behind one OpenAI-compatible key, which simplifies writing a single validated card shape regardless of which model produced the fields.