Skip to content

Schema members ​

Every entity carries four plain ZodObjects as statics, a fifth describing its JSON form, plus the class itself.

Snippets on this page assume these imports:

ts
import { z } from "zod";
import { Entity } from "@btravstack/entity";
ts
Organization.input; // ZodObject — everything make() accepts
Organization.output; // ZodObject — stored state, internal fields included
Organization.createInput; // ZodObject — input minus the generated fields
Organization.updateInput; // ZodObject — input minus the immutable fields, partial
Organization.json; // ZodObject — what z.encode(output, toJSON()) writes
Organization.entityName; // the tag, as a literal type
Organization; // …is itself a zod schema, parsing to an instance

output is input plus the computed fields. All four ZodObjects are plain all the way down, so they generate JSON Schema in both "input" and "output" directions, nested entities included. A field whose own type JSON Schema cannot express is the exception; see What JSON Schema can express.

Each describes what the domain accepts or holds, whoever is asking:

MemberDescribesIs not
inputevery field make() readsa request body: it includes the generated fields
outputthe stored state, every field includeda response body: an internal field is in it too
createInputevery field a create may seta public command: internal fields are in it too
updateInputevery field the domain lets changeauthorization: mutable does not mean any caller may set it
jsonthe stored state as JSON, codecs encodeda response body: an internal field is in it too

They are building blocks for a contract. A public route selects from them with .pick, an allowlist, so a field the entity gains later is not exposed by default. Expose an HTTP contract has the recipe. Converting a member to JSON Schema selects nothing: it describes every field the domain holds, internal ones included.

Nested entities ​

When a field holds another entity, each member embeds that entity's own plain schema, never its class. Which one depends on the member:

MemberA nested entity becomes
inputits input
outputits output, computed fields included
createInputits input
updateInputits input, as an optional key
jsonits json

The substitution goes through z.array(...), z.optional(...), z.nullable(...) and Entity.field(...), and it repeats at every level, because the nested entity's own members are already plain. An Entity.union(...) field becomes the union's input or output: a z.discriminatedUnion of its members' plain schemas.

ts
class Order extends Entity("Order")({
  id: OrderId,
  lines: z.array(OrderLine), // OrderLine declares a computed `subtotal`
}) {}

z.toJSONSchema(Order.output, { io: "output" }); // ✓ lines[] carry `subtotal`
z.toJSONSchema(Order.createInput, { io: "input" }); // ✓ lines[] do not
Order.output.parse(order.toJSON()).lines[0]; // plain data, not an OrderLine
Order.make(row).getOrThrow().lines[0]; // an OrderLine instance

Parsing with a member gives plain data at every depth. Construction is unchanged: make, update and a factory parse through a module-private schema that keeps the classes, so a nested field still holds a real instance. The class used as a schema delegates raw input directly to make, so nesting adds no validation passes, regardless of parent depth. A transform that appends text or changes its output type behaves the same when nested as when made directly. Re-entering stored output through another make remains a new validation pass; this does not change the requirement that fields accept their own output for rehydration and update.

What is not walked: an entity inside z.record(...), z.tuple(...), .default(...), .readonly() or an inline z.object(...) stays the class, and the member that holds it does not convert. .describe() or .meta() written on an array or optional wrapper around an entity is not carried over; put it on the entity's own schemas or on the contract you derive.

A serialised entity parses with its own output, and make takes the result back:

ts
const wire = JSON.parse(JSON.stringify(order));
const decoded = Order.output.parse(wire); // equals `wire`
Order.make(decoded); // Ok(Order), nested lines rebuilt as instances

That holds as long as every field survives JSON.stringify, which the next section qualifies.

What JSON Schema can express ​

The package invents no encoder. Each member holds your field schemas as you wrote them, so what converts is what zod converts:

A field declared asParsing a memberz.toJSONSchema, io: "input"z.toJSONSchema, io: "output"
z.iso.datetime() (branded)a string✓ format: "date-time"✓ format: "date-time"
z.date()a Date✗ throws✗ throws
z.bigint()a bigint✗ throws✗ throws
z.custom(...), z.instanceof(...)the value you passed, untouched✗ throws✗ throws
a .transform(...)the transformed value✓ the source schema✗ throws
a z.codec(wire, domain, ...)the decoded (domain) value✓ the wire schemathe domain schema; ✗ if a Date
Entity.codec(wire, domain, ...)the decoded (domain) value✓ the encoded wire schema✓ the encoded wire schema

Entity.codec publishes its encoded wire schema even when nested in an ordinary z.object, array, optional or nullable field. Native values such as Temporal.PlainDate and Temporal.Instant remain the parsed application values; the generated JSON Schema describes their declared JSON strings. Descriptions, metadata and recursive wire references follow Zod's ordinary conversion.

Two of those rows also break the round trip above, before JSON Schema is involved: JSON.stringify writes a Date as a string, which z.date() then rejects, and throws on a bigint outright. For a value that crosses a JSON boundary, declare the JSON-safe form as the field: an ISO string through z.iso.datetime().brand(...), an amount in integer minor units, a decimal as a string.

Where a field must stay unrepresentable, convert with { unrepresentable: "any" }. zod then writes {} (any value) for that property instead of throwing, and documents nothing about it:

ts
z.toJSONSchema(Ledger.output, { unrepresentable: "any" }); // ✓ the bigint field is {}

The JSON form: json ​

A field whose value JSON cannot hold — a bigint, a Temporal.Instant — is declared with Entity.codec. make takes its wire text or its value, the entity stores the value, and json describes the text:

ts
const Cents = Entity.codec(z.string().regex(/^-?[0-9]+$/), z.bigint().brand("Cents"), {
  decode: (text) => BigInt(text),
  encode: (cents) => String(cents),
});

class Account extends Entity("Account")({
  id: Entity.field(z.uuid().brand("AccountId"), { identity: true }),
  balance: Cents,
}) {}

z.toJSONSchema(Account.json, { io: "output" }); // ✓ balance is a string

json is the schema of what z.encode(output, x.toJSON()) writes: each codec field as its wire side, a nested entity or union as its own json, generated and computed fields included and an unset optional omitted, as in toJSON(). It is a plain ZodObject, so a contract picks its response from it, and the handler encodes the matching pick of output:

ts
const AccountView = Account.json.pick({ id: true, balance: true });

declare const account: Account;
const body = z.encode(Account.output.pick({ id: true, balance: true }), {
  id: account.id,
  balance: account.balance,
}); // { id: "…", balance: "1250" }, which AccountView parses

Encoding a whole toJSON() takes a cast — account.toJSON() as unknown as z.output<typeof Account.output> — because toJSON() is deep-readonly and types a nested entity as its instance, while z.encode wants the schema's plain output. The data is the same.

A field's wire schema is what json publishes for it, so make it the canonical spelling encode writes: a codec whose wire side is z.iso.datetime({ offset: true }) describes every offset decode accepts, not the one form encode emits.

Why a codec field is Entity.codec and not a bare z.codec. A field must accept its own output: make(toJSON()), update and a nested entity's construction all parse the decoded value again, and a bare codec refuses it. Entity.codec is z.union([z.codec(wire, domain, …), domain]), codec first. The order matters as much as the union: z.encode takes the first member that accepts a value, so with the domain member first a body carries the bigint itself.

json collapses Entity.codec's union to its codec's wire side, and that union alone — it is marked, and the mark survives .describe() and .meta(). A union written by hand keeps every member, each in its own JSON form, so a z.union([z.codec(…), value]) of your own keeps its bigint and converting json throws. That is deliberate: a type cannot tell which schema object a member is, so a rule that dropped one by matching it would type a field the validator still parses differently. A codec whose wire side is itself a codec is followed to the end of the chain, as z.encode follows it.

The class as a schema ​

The class carries zod's internal slots (_zod, ~standard) but not its methods, so it composes anywhere zod takes a schema while .parse() — which throws — does not exist on it:

ts
z.object({ owner: Organization }); // ✓
z.array(Organization); // ✓
z.optional(Organization); // ✓ the function form
Organization.optional(); // ✗ does not exist
Organization.parse(raw); // ✗ does not exist — use make()
z.toJSONSchema(Organization, { io: "output" }); // ✗ throws — the class carries a transform

That last line holds whether or not the entity nests anything. It is the design rule made concrete: contracts compose the four plain ZodObjects; domain code composes the class itself. See Why entity? for the constraint it comes from, and Expose an HTTP contract for the recipe.

Released under the MIT License.