typebox-model-schema

Create one <model>.schema.ts file exporting Item, Row, LookupRow, payload, and response schemas with Type.Object, and derive types via Static<typeof Schema>. The same file serves backend validation and frontend form generation, so it must not import server-only or client-only modules.

Standard annotations like title, minLength, and format set labels and validation, while custom x-form, x-list, and x-lookup annotations declare which fields appear in forms, list columns, and pickers. Width values like sm, md, and lg control column sizing.

JavaScript numbers lose precision above 2^53, so bigint database ids travel as strings in JSON. Annotate these fields with x-db-type: bigint to document the database type while keeping Type.String() in the schema.

Use UUID only when an entity genuinely needs non-sequential, globally unique identifiers, such as external integrations, distributed generation, or public-facing tokens. Ordinary catalog and document models should use bigint identity starting at 100.

If a register row can be written by multiple document types, an x-ref naming one model joins only through that model's table, leaving other rows silently empty. Use x-ref with entity: document instead so the join goes through the shared document header.

x-transient marks a field that exists in the form type but has no database column, such as the display object next to a reference field. The generator skips it when building SQL, preventing errors like column does not exist at publish time.