nullish()

skills/criar-schema-zod/SKILL.md

@@ -72,6 +72,26 @@ export const zUsuarioCriar = z.object({
 | `z{Modulo}Config` | Configuração |
 | `z{Modulo}Ambiente` | Variáveis de ambiente |
 
+### 2.4. Colunas e Campos que Podem ser Nulos: Usar `.nullish()`
+
+Toda coluna do banco de dados relacional ou campo de entidade/registro que puder ser nulo ou omitido **DEVE** utilizar `.nullish()` (nunca `.optional()` ou `.nullable()` isolados):
+
+```typescript
+// ✅ CORRETO — aceita null (do banco PostgreSQL) e undefined (payload omitido)
+export const zPontoCriar = z.object({
+  nome: z.string().min(1),
+  descricao: z.string().max(5000).nullish(),
+  codigo_empreendimento: zUUID.nullish(),
+  coordenadas: zCoordenadas.nullish(),
+})
+
+// ❌ ERRADO — quebra com null retornado pelo Knex/PostgreSQL
+descricao: z.string().optional(),
+
+// ❌ ERRADO — quebra quando a chave é omitida no payload (undefined)
+descricao: z.string().nullable(),
+```
+
 ---
 
 ## PASSO 3 — Derivar o Tipo com `z.infer<>`
@@ -175,6 +195,7 @@ Zero erros = concluído.
 - [ ] A validação usa `safeParse` (exceto em boot/middleware)?
 - [ ] A nomenclatura segue o padrão `z{Entidade}{Acao}`?
 - [ ] Transformações (trim, coerce, default) estão no schema, não no handler?
+- [ ] Colunas e campos que podem ser nulos/opcionais utilizam `.nullish()` (em vez de `.optional()` ou `.nullable()` isolados)?
 - [ ] Schemas derivados usam composição (.partial, .extend, .pick), não duplicação?
 - [ ] `tsc --noEmit` passa sem erros?