Forward compatibility

APIs grow. A new enum member, a new response field — neither is a breaking change on the server, and neither should break an SDK a consumer pinned last quarter. Generated SDKs are built so they don’t.

Three guarantees, all on by default, none requiring a regeneration to benefit from:

• Open enums — a value outside the set the SDK was generated from decodes, round-trips, and is detectable.
• Unknown response fields — a field the SDK was never generated from is retained on decode and written back out.
• Per-call escape hatches — you can send parameters your spec doesn’t model yet.

Open enums

When your server starts returning status: "archived" and the SDK was generated when the set was active | inactive, a conventional generated enum throws on decode. Glotto’s don’t. An unrecognized value satisfies three properties:

1. It decodes without crashing. No exception, no dropped response.
2. It round-trips at its original value. Read-modify-write sends archived back, not a fallback or a null.
3. It is detectable. You can tell a server-added value from a known member and branch on it.

This holds for string enums and, since Glotto took the deferred integer decision, for numeric enums too — the same three-part contract over a different primitive.

In TypeScript that surfaces as an open union, so the known members still autocomplete while any other value is accepted:

    Message:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - user
            - assistant
        content:
          type: array
          items:
            $ref: '#/components/schemas/ContentBlock'

    ErrorResponse:
      type: object
      description: The body every operation returns when a request fails.
      required:
        - status
        - message
      properties:
        status:
          type: integer
          description: The HTTP status the request was answered with.
          # A NUMERIC enum, open on the same three-part contract a string one is:
          # a status this SDK predates decodes, round-trips, and is detectable.
          enum:
            - 400
            - 401
            - 429
            - 500
        message:
          type: string

export type MessageRole = 'user' | 'assistant' | (string & {});

export type ErrorResponseStatus = 400 | 401 | 429 | 500 | (number & {});

Checking for a value this SDK predates is the comparison you would write anyway: it equals none of the members above. Log it, route it, or ignore it — it survives re-encoding either way.

The & {} is load-bearing, not noise. A plain 'active' | 'inactive' | string collapses to string and discards the known members — which are the documentation of what the API actually accepts.

How it surfaces in your language

Every engine keeps the same guarantee and spells it the way its language already handles extensible values:

Open unions are 'a' | 'b' | (string & {}) and 200 | 404 | (number & {}).

For PHP, the exact surface is Status|string: the generated enum united with its primitive.

The passthrough row is not a weaker guarantee, just a different one: in those languages the declared type never constrained the value in the first place, so an unrecognized member was always going to arrive intact. The comparison you write is the same.

Mixed and boolean enums stay closed by design. A mixed enum has no single primitive to be open over, and a boolean enum is already total — there is no value outside true | false to be forward-compatible with.

Unknown response fields

The second leg covers fields rather than values: a response field your SDK was never generated from is retained on decode, readable through an accessor, and written back out on re-encode — so a read-modify-write never silently deletes data the SDK didn’t recognize.

Each language page documents the accessor its engine emits, in that language’s idiom: TypeScript · Python · Go · Ruby · Elixir — and the same section on every other Languages page.

Sending what your spec doesn’t model yet

The retained fields above are read-only by design: they record what the SDK received. To send a parameter your spec doesn’t model yet, use the per-call extra-query and extra-body escape hatches rather than writing into the retained bag. That keeps the two directions honest — retention is a record of the wire, and anything you add is something you chose to send.

Why this matters more than it sounds

Forward compatibility is what makes a pinned SDK safe to leave pinned. Without it, every additive server change is a silent deadline: consumers on older SDKs start throwing on values you consider non-breaking, and you find out from their bug reports. With it, the additive change is exactly what you intended it to be.