AI Scheduling API Versioning: Change the Contract Without Stranding Open Meetings

Version the API without rewriting an open hard meeting

Use one meeting that remains open through a deployment: four required people, two optional people, Google and Microsoft calendars, one unconnected participant, three IANA zones, an outstanding reminder, a pending approval, one provider retry, and a new API contract that adds substitutes and changes error structure.

1. 1

   Persist a versioned meeting-intent envelope before side effects

   Store meeting ID, authenticated organizer, purpose, duration, bounded date range, booking deadline, IANA meeting zone, required and optional participant entities, approved substitutes, working hours, buffers, outreach authority, disclosure, approval mode, organizer calendar, and terminal proof. Add immutable wire_schema_version, domain_schema_version, workflow_version, policy_version, and provider-adapter versions.
   • Required attendance cannot change because an absent field receives a new default.
   • The original request and normalized intent remain linked as provenance.
   • A missing identity, zone, or authority enters a typed exception instead of a guessed migration.
2. 2

   Separate transport, domain, workflow, policy, and provider versions

   The REST or MCP input schema controls what clients may send. The domain schema controls how the meeting is stored. Workflow code controls valid transitions and durable waits. Policy controls attendance, reminders, approvals, evidence freshness, and disclosure. Provider adapters control Google and Microsoft request and response mapping. Give each boundary its own version so one compatible wire change does not silently alter an in-flight decision.
   • API documentation version is not treated as the workflow version.
   • A provider SDK upgrade cannot rewrite participant policy by accident.
   • Every terminal result records the versions that produced it.
3. 3

   Make the edge additive and normalize once

   Prefer additive optional fields, explicit enums with unknown handling, and stable identifiers. Validate client input against the declared REST or MCP schema, then normalize it into one supported domain version before outreach. Reject incompatible ambiguity with a typed problem response. Never let every worker reinterpret raw client payloads under whichever code happens to be deployed that day.
   • New optional fields have declared semantics and do not change old defaults.
   • Unknown enum values survive or fail according to a documented compatibility rule.
   • OpenAPI or MCP validation proves shape, not organizer consent or meeting authority.
4. 4

   Pin open meetings to deterministic workflow behavior

   When a meeting starts, bind its workflow and policy versions. Route every timer, participant reply, webhook wake-up, retry, approval, and provider result back to workers that understand those versions. Keep old code paths available while open instances depend on them. Microsoft’s Durable Functions guidance shows why adding, removing, or reordering durable calls can break replaying instances; scheduling workflows have the same practical risk even on another engine.
   • A deployment cannot insert a new reminder or calendar write into old execution history by surprise.
   • Old instances do not deserialize a changed activity result into a new incompatible type.
   • Routing and retention metrics show how many meetings remain on each version.
5. 5

   Migrate only at a named safe checkpoint

   Define checkpoints such as intent accepted before outreach, evidence complete before proposal, or proposal expired before recompute. A migration reads old state, verifies organizer authority, maps participants and evidence without loss, writes a new revision plus migration receipt atomically, and schedules the next action under the new version. Do not migrate across an uncertain message delivery, provider write, consent change, or pending approval.
   • Every required and optional role has an exact target mapping.
   • Connected free/busy and conversational windows keep source, zone, freshness, consent, and expiry.
   • A failed migration leaves the old instance runnable rather than half-converted.
6. 6

   Run old and new provider and fallback paths against fixtures

   Replay redacted fixtures for Google free/busy, Microsoft getSchedule, provider denial, revoked access, empty busy results, duplicate webhooks, and event-write timeouts. Run conversational replies with missing dates, ambiguous zones, correction, silence, opt-out, and late arrival. Compare normalized evidence and next decisions under both versions before shifting live meetings.
   • Provider response fields that disappear or change type fail closed.
   • Calendar connection remains optional; migration does not delete the no-sync path.
   • A response parser upgrade cannot turn unknown availability into a slot.
7. 7

   Keep side-effect identity and consent stable across versions

   Namespace idempotency by logical meeting action, not deployment. A reminder already sent under version one remains the same reminder when version two receives the retry. Re-check current meeting revision, participant consent, evidence freshness, approval, and provider authority before every side effect. Reconcile uncertain writes before replay and keep old and new workers from claiming the same action concurrently.
   • A migration cannot send a second participant request for the same purpose and deadline.
   • Retry budgets and reminder caps survive version changes.
   • New code cannot widen participant, disclosure, time, or calendar scope during replay.
8. 8

   Verify completion and retire a version with evidence

   Before reporting booked, read back the canonical organizer event and verify provider identity, calendar, start, end, zone, every required attendee, approved optional decisions, and conferencing or location. Trace the meeting from client contract through normalization, pinned workflow, participant evidence, migration if any, provider calls, retries, repair, and terminal proof. Retire old workers only when no runnable, waiting, repairable, or replayable meeting still references them.
   • A successful migration is progress, not meeting completion.
   • Dashboards expose version population, oldest open instance, migration failures, replay errors, and completion rate by version.
   • Rollback restores compatible workers and routing without changing action identities.

Compare API versioning by what happens to open meetings

The deciding test is whether a deployment can change contracts and workers while every waiting participant and uncertain provider action remains safe and recoverable.