Schemas at the boundary
effectProviderPlugin makes Effect Schema the validator and the serializer:
S.decodeUnknown on the way in, S.encodeUnknown on the way out. So the schema’s
decoded type is what controllers see, and the encoded type is what travels —
a S.BigInt field is a bigint in your code and a string on the wire, and the
transformation happens in one place.
Serialization is strict. A response that does not match its schema throws
ResponseSerializationError (500) with the parse error logged, rather than sending a
body the OpenAPI document does not describe — loud and early, by
design.
Two helpers exist because JSON Schema generation needs a hint:
import { BigIntIdSchema, parseJsonParam } from "@kylobyte/keel";
// A 64-bit id: `bigint` in code, string in JSON, documented as a stringparams: S.Struct({ id: BigIntIdSchema }),
// GET /users?filter={"role":"admin"} — validated as an object, documented as onequerystring: S.Struct({ filter: S.optional(parseJsonParam(UserFilterSchema)) }),Without the annotations, the generated document would describe the decoded bigint
and a bare string respectively.
Schemas are also where response shaping happens. Keep a schema per resource in
*.schemas.ts and derive the types from it, so the response type and the document
stay one artifact:
export const UserSchema = S.Struct({ id: BigIntIdSchema, name: S.String, email: S.NullOr(S.String), createdAt: S.Date,});export type User = S.Schema.Type<typeof UserSchema>;