How should teams evolve function schemas and Structured Outputs without breaking live conversations?

When a team changes a function schema, it is usually changing two different contracts at once. The first is the proposal surface: the tool definition or Structured Outputs schema that tells the model which shape to emit. The second is the server-side contract that accepts, normalizes, and executes that shape. Those surfaces can drift independently, and live conversations fail when they do. A field rename, a new requirement, or a stricter object shape is therefore a behavioral change, not a cosmetic one.

The OpenAI docs make that boundary visible. Function calling defines tools with JSON Schema and returns function_call items whose arguments your application must interpret. Structured Outputs uses a schema to constrain what the model can emit directly. In both cases, the schema is part of runtime behavior. A change to that schema can break an in-flight conversation even if the underlying business intent has not changed.

That is why the implementation in this article keeps the wire shape versioned and the application shape canonical. The model can be guided toward a newer schema while the server continues to recognize older shapes during a transition window. The goal is not to keep every old payload valid forever. The goal is to decide exactly which old payloads are still acceptable, which are rejected, and how accepted values become one stable internal object.

Strict schemas are useful because they fail loudly. The guides say that strict mode requires additionalProperties:false and that all fields must be required. They also say that unsupported schema keywords are rejected. That is the right behavior when the question is, “Did the model propose something outside the contract?” A loud failure is better than quietly handing a malformed payload to application code.

But strictness is not the same thing as compatibility. If you replace one schema with another in place, older conversations do not magically rewrite themselves. A payload that used `orderId` yesterday may still arrive tomorrow, even if the model is now encouraged to emit `order_id`. A schema that adds a required field can also strand a conversation that started under the previous version. Strict mode protects the boundary; it does not invent a migration path.

The fixture behind this article treats that distinction as the core design decision. Validation decides whether a payload is acceptable for a specific schema version. Adaptation decides whether an accepted payload can be translated into the canonical internal shape. Those are different jobs. If you collapse them into one step, you lose the ability to explain whether a failure came from the model proposal, the version bridge, or the business logic that follows.

The implementation uses two wire schemas. Version 1 exposes `orderId` and `items`. Version 2 renames the order field to `order_id` and adds `priority`. The important decision is that no downstream code is allowed to depend on either wire shape directly. Instead, the application consumes one canonical object: `{ orderId, items, priority }`. That canonical shape is what the rest of the system sees, stores, and reasons about.

The adapter function is the compatibility policy. If it sees a v1 payload, it reads `orderId` and defaults `priority` to `false`. If it sees a v2 payload, it reads `order_id` and converts `priority` from `true`, `false`, or `null` into the same canonical field. If it sees neither shape, it throws. That failure is intentional. An unrecognized payload should not be guessed into existence just because the surrounding workflow would prefer a best-effort answer.

This separation keeps schema evolution local. You can introduce a newer model-facing schema without forcing every consumer to understand both wire formats forever. At the same time, you can keep replayed conversations alive during a migration because the adapter remains responsible for the old version. The rest of the app only sees one stable representation, which is exactly the shape you want for business logic and persistence.

The regression tests are small on purpose. One test feeds a v2-shaped JSON string into the v2 schema and expects the canonical normalized object in return. That proves the accepted path: a current payload can pass validation and be adapted into the internal contract. Another test removes the `items` field and expects a rejection that names the missing required field. Another adds an unexpected property and expects `additionalProperties:false` to reject it. Those are the exact failure modes the documentation warns about, and the test names make those failures visible.

A separate test covers the v1 shape. It validates that the older payload still passes the v1 schema and that the adapter fills the canonical default for `priority`. That is the compatibility window this article is really about. The server can keep old conversations alive while the model moves forward to the newer wire shape. If you removed the adapter and swapped only the schema, that older payload would stop being safe to replay.

The last test throws on an unrecognized object. That matters because the adapter is not a permissive parser. It should not guess at missing fields or synthesize meaning from a random object. The point of the boundary is to recognize known versions and fail closed on everything else. The test suite proves that distinction, but it does not prove anything about the live OpenAI service or about a full agent loop. It proves the contract that the application owns.

Two edge cases need an explicit policy, because the docs do not decide them for you. The first is a rename. A rename is a breaking change unless the compatibility layer understands both names during the migration window. If a live conversation still emits the old field name and the new handler only knows the new one, the conversation breaks even if the rest of the payload is valid. That is why version markers and adapters matter: they let you recognize which shape you received instead of guessing from a partially overlapping set of keys.

The second edge case is null as an optional stand-in. Structured Outputs requires all fields to be required, so the docs recommend a null union when you need an optional-like field. In the fixture, `priority` is declared as `['boolean', 'null']`, which makes the field required while still allowing the model to express “present, but undecided” as null. The adapter then chooses the application default of `false` for v1 payloads and converts a v2 null to the same canonical meaning. That keeps the schema valid without pretending the model can omit the field entirely.

A third edge case is schema shape itself. The Structured Outputs guide rejects root-level anyOf, requires additionalProperties:false, and excludes several JSON Schema keywords. That means a migration plan cannot rely on the broadest possible schema language. If a desired compatibility shape depends on unsupported constructs, move the compatibility logic into the server adapter instead of trying to force the schema to carry every rule. The schema should constrain proposal shape; the adapter should carry compatibility policy.

The simplest rule that survives production pressure is this: version the schema the model sees, normalize at the server boundary, and never let downstream code depend on the wire shape. That rule gives you a migration window, a single canonical internal object, and a clear place to reject malformed proposals. It also keeps the rollout reversible. If the new schema causes trouble, you can keep accepting the older one while you revise the model-facing hint or the adapter.

That approach matches the official guidance instead of fighting it. The function-calling guide explains how to define tools and handle function calls. The Structured Outputs guide explains which schema shapes are supported and which are rejected. What those docs do not give you is a live-migration playbook for conversations already in flight. The versioned-schema pattern fills that gap without pretending the platform will maintain compatibility for you.

The useful outcome is practical, not theoretical. New conversations can move toward the newer schema. Old conversations can continue to resolve through the adapter while they are still valid. Invalid payloads still fail loudly. And every downstream consumer sees the same canonical shape, which keeps the rest of the application simple even while the wire contract changes around it.