shorn: your Zod schema already describes the payload, so why send the keys?

[ChiChuRita]

I built shorn. It uses the Zod schema you already have as a binary wire format. Both sides have the schema, so field names never go in the payload.

const Person = z.object({
  name: z.string(),
  age: z.int().nonnegative(),
  sex: z.enum(["male", "female", "other"]),
});

const bytes = encode(Person, { name: "Colin", age: 24, sex: "male" });
// keys live in Person, so only the values go out: ["Colin", 24, "male"] in binary format
// 8 bytes, against 38 as minified JSON

decode(Person, bytes); // { name: "Colin", age: 24, sex: "male" }

It's also faster. JSON has to write every key and parse it back out again. shorn skips that work entirely, so it's up to 6.2x faster to encode and 14.5x to decode in my benchmarks. The saving comes from the schema, not from compression, so there's no CPU cost to pay for it.

No IDL, no codegen, no second schema. It reads validation through Standard Schema and structure through Standard JSON Schema.

Playground: https://shorn.dev

One question, since I depend on it: how stable is the toJSONSchema output? I pick encodings from the emitted keywords. minimum or exclusiveMinimum gives an unsigned varint, prefixItems means a tuple, anyOf and oneOf mean a union. If those change shape, saved payloads stop decoding. I checked #6339 and my bytes are identical either way. The docs mark fromJSONSchema experimental but say nothing about toJSONSchema.

[dosubot[bot]]

Hi @ChiChuRita! I'm Dosu and I'm helping the Zod team. shorn sounds like a really clever idea — using the schema as the wire format is an elegant reuse of something you're already paying for.

On your stability question: z.toJSONSchema() is not marked experimental — only z.fromJSONSchema() carries that label [1]. That said, there's no explicit long-term stability guarantee written for toJSONSchema's output shape either, so it's worth understanding what is and isn't likely to change.

Here's what I can tell you about the specific keywords you depend on:

• minimum / exclusiveMinimum — The output varies by target. With the default "draft-2020-12", exclusive bounds use the numeric exclusiveMinimum form; with "draft-04" or "openapi-3.0" it emits the legacy minimum + exclusiveMinimum: true form [2]. Pin to a specific target (or handle both forms) and you should be safe.

• prefixItems — Used for tuples in "draft-2020-12". Older targets like "draft-07" and "draft-04" use items (as an array) instead, since prefixItems was only introduced in 2020-12 [2]. Again, target-dependent.

• anyOf vs oneOf — Inclusive unions (z.union()) emit anyOf; discriminated unions emit oneOf [2].

What has changed recently: v4.4.0 shipped a fix where $defs entries no longer include a redundant id field (#5759), which may affect consumers reading those internal id fields. Other JSON Schema fixes in that release (Draft-04/OpenAPI 3.0 min/max intersections, lazy schema handling, etc.) were correctness fixes [3].

Practical advice: Pin to a specific target (e.g. { target: "draft-2020-12" }) and treat the output as conforming to that JSON Schema dialect rather than depending on Zod-specific structural choices. Since toJSONSchema aims to produce valid JSON Schema, its output should remain stable for a given target as long as JSON Schema draft specs don't change. The override callback is also available as an escape hatch if you ever need to adapt to a change [2].

For the most authoritative answer on stability guarantees, you'd want to hear from @colinhacks directly — I'm not aware of any explicit written promise on toJSONSchema output stability beyond "this is a first-party stable (non-experimental) feature."

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[amasen02]

Stability of z.toJSONSchema() in Zod 4

To answer your core question directly: The output structure of z.toJSONSchema() for standard primitives and structural combinators is treated as stable and normative under SemVer, specifically because the wider ecosystem (OpenAPI generators, AI function-calling schemas, and tooling) depends on deterministic output.

Here is what you can rely on, along with two critical architectural caveats for binary wire serialization:

---

1. What is Guaranteed and Stable

1. Standard Specification Target (Draft 2020-12):
   Zod 4’s toJSONSchema targets JSON Schema Draft 2020-12. This means:
   • Tuples will consistently emit prefixItems (not the obsolete Draft 7 array-of-schemas items).
   • Discriminated unions and unions emit standard anyOf / oneOf.
   • Numeric constraints map to standard keywords: minimum, maximum, exclusiveMinimum, and exclusiveMaximum.
2. Why fromJSONSchema is experimental while toJSONSchema is not:
   • fromJSONSchema must ingest arbitrary, potentially invalid or under-specified external JSON Schemas and attempt to synthesize a runtime type-checking function. That heuristic mapping is inherently experimental and prone to edge-case adjustments.
   • toJSONSchema is a unidirectional, deterministic projection from Zod's internal definition tree (_zod.def). Changing the emitted keywords for existing types would break downstream validation and is governed by strict breaking-change SemVer policies.

---

2. Critical Caveats for a Positional Binary Wire Format (shorn)

Because you are mapping field values to positional binary payloads (["Colin", 24, "male"]) based on schema introspection, watch out for these two behaviors:

A. JSON Schema Object Key Ordering (RFC 8259)

In JSON Schema, the properties map is a JSON object, and JSON specifications (RFC 8259) do not guarantee semantic key ordering. While JavaScript engines preserve string key insertion order, operations such as:

• .extend()
• .merge()
• .pick() / .omit()
• Or potential future internal schema tree optimizations

can reorder the emitted entries in properties: { ... }.
Recommendation: If you derive positional tuple indexes from properties, enforce a canonical key sort (e.g. alphabetical by property name) on both the encoder and decoder before indexing offsets. This ensures identical wire positions regardless of how the schema was composed.

B. anyOf vs oneOf in Unions

For standard unions (z.union), Zod emits anyOf. For discriminated unions (z.discriminatedUnion), Zod may emit oneOf with properties.<discriminator>.const (or enum: [value]). If your wire format distinguishes between disjoint and non-disjoint unions, ensure your decoder treats both anyOf and oneOf with matching variant structures interchangeably.

---

Summary

For core keywords (minimum, prefixItems, enum, properties), toJSONSchema is rock solid. Enforcing canonical property ordering on your introspection layer will make shorn completely immune to schema composition order shifts.