z.toJSONSchema plugin API: shape proposal

[dokson]

Context

@colinhacks hinted at a future plugin API for z.toJSONSchema to replace ad-hoc parameter additions:

Very allergic to additional params on this function. I'm considering a plugin API that would give Zod the ability to encapsulate some of these common overrides and provides them to users via a consumable API.

This discussion is to put a concrete shape in front of that idea so it has something to react to, rather than starting from scratch when it's time to build it.

Motivating use cases

Three open issues all reduce to "downstream consumer doesn't accept a JSON Schema keyword Zod legitimately emits":

Issue	Consumer	Need
#5807	Google Gemini Function Calling	z.union(...) → oneOf instead of anyOf (Gemini rejects anyOf)
#5493	Older OpenAPI / language-binding generators	Same — oneOf for inclusive unions
#5494	Swagger / OpenAPI codegen	Same

Each can be solved today with a hand-rolled override, but every project hitting the issue rewrites the same logic, and the post-walk approach has minor footguns (the path arg in nested overrides references the original keyword).

Proposed shape

A plugin is a value of type JSONSchemaGeneratorParams — i.e. the same options bag toJSONSchema already accepts. Plugins compose by deep-merging override (chained) and shallow-merging the rest.

type JSONSchemaPlugin = JSONSchemaGeneratorParams & { name?: string };

function withPlugins(
  ...plugins: Array<JSONSchemaPlugin | JSONSchemaGeneratorParams>
): JSONSchemaGeneratorParams;

Usage:

// User-defined plugin
const myPlugin: JSONSchemaPlugin = {
  name: "my-tweaks",
  override(ctx) { /* ... */ },
};

// Built-in plugin
z.toJSONSchema(schema, withPlugins(z.plugins.geminiCompat));

// Composition with user options
z.toJSONSchema(schema, withPlugins(
  z.plugins.geminiCompat,
  { override: ctx => { /* my custom tweaks, runs after geminiCompat */ } }
));

Why this shape

1. Plugins are not a new concept — they are pre-built JSONSchemaGeneratorParams. No new type to learn; users already know the options bag.
2. withPlugins is opt-in — toJSONSchema itself stays untouched. Users who don't need plugins never encounter them.
3. Composition is explicit — override callbacks chain in declaration order, other fields shallow-merge with last-wins semantics.
4. Built-ins are namespaced — z.plugins.<name> keeps discovery cheap from the IDE without bloating the top-level export.

First built-in: z.plugins.geminiCompat

export const geminiCompat: JSONSchemaPlugin = {
  name: "gemini-compat",
  override(ctx) {
    if (ctx.zodSchema._zod.def.type === "union" && ctx.jsonSchema.anyOf) {
      ctx.jsonSchema.oneOf = ctx.jsonSchema.anyOf;
      delete ctx.jsonSchema.anyOf;
    }
  },
};

Could be expanded later (Gemini also rejects some other keywords) without breaking the call site.

Possible follow-up plugins

• z.plugins.swagger2() — Swagger 2 / OpenAPI 2 compatibility (no anyOf, no examples, etc.).
• z.plugins.openaiStructuredOutput() — OpenAI's structured-output strict mode.
• z.plugins.draft07() — already covered by target, but could fold in legacy quirks consumers expect.

Questions for @colinhacks

1. Is JSONSchemaPlugin = JSONSchemaGeneratorParams & { name? } close to what you had in mind, or were you thinking of something with a richer surface (lifecycle hooks, ordering control, etc.)?
2. Do built-in plugins live under z.plugins.*, a separate import (zod/plugins), or stay external entirely?
3. Should withPlugins be exposed (z.toJSONSchema.with(...) chainable, or z.plugins.compose(...)), or do callers just spread plugin objects manually into the params bag?

If the shape is roughly right, happy to draft a PR. If not, useful to know what to pivot to before sinking time.