Data field validation

mandatory

Regras canônicas de validação de campo na Koder Stack — required, format/pattern, length/range, check-digit (CPF/CNPJ), cross-field, e o contrato de onde a validação roda (client + server, server é autoridade). Define como uma falha de validação vira erro de classe `VL` e popula o array `fields` do envelope (`specs/errors/model.kmd`). Pareada com `specs/data/field-types.kmd` (tipos) e `specs/data/masks.kmd` (apresentação).

Facet Data + Interface. Define as regras que um valor deve satisfazer. O tipo/storage é field-types.kmd; a máscara é masks.kmd; a falha é um erro de classe VL (errors/taxonomy.kmd) carregado pelo array fields do envelope (errors/model.kmd).

Applicability

Toda validação de valor de campo em componente Koder — formulários (UI), payloads de API (backend), argumentos de CLI. Aplica-se a input de usuário e a dados que cruzam um boundary. Não se aplica a invariantes internas de código (isso é assertpanic de `codeerror-handling.kmd §R2`).

R1 — Tipos de regra (enum)

Regra Significado Param
required Valor presente e não-vazio —
format Casa um pattern (regex / format de field-types.kmd §R4) pattern
length Comprimento de string em [min,max] min, max
range Valor numérico/data em [min,max] min, max
enum Pertence a um conjunto fechado values
check-digit Dígitos verificadores válidos (CPF, CNPJ) algoritmo
cross-field Coerência entre campos (end ≥ start, confirm == senha) expr
unique Único no escopo (server-side; respeita multi-tenancy) escopo

Regras compõem: um campo cpf required valida presença e check-digit.

R2 — Onde a validação roda (client + server)

  1. Server é a autoridade. Toda regra deve ser revalidada no servidor,

    independentemente da validação de cliente. Cliente nunca é confiável.

  2. Cliente valida para UX — feedback imediato (ícone ✓/✗ de

    text-fields.kmd/phone-input.kmd §R4), antes do submit. É espelho da regra do servidor, não substituto.

  3. Mesma regra, uma fonte — a regra é declarada uma vez (schema JSON

    Schema draft 2020-12, extract-RFC-001) e consumida por client e server; não duplicar a lógica em dois lugares com risco de divergir (policies/reuse-first.kmd). O koder_kit expõe o validador headless.

R3 — Regras de preenchimento por tipo semântico

Validação default dos tipos de field-types.kmd §R2 (produto pode tighten, nunca loosen):

Tipo Regras default
email required? + format (RFC 5321)
phone format E.164 válido p/ país (libphonenumber)
cpf length=11 dígitos + check-digit (mód-11)
cnpj length=14 dígitos + check-digit (mód-11)
cep length=8 dígitos + format
money range ≥ 0 (salvo regra) + 2 casas decimais p/ BRL/USD
date/datetime format ISO + range plausível (não ano 0000)
url format absoluta + scheme HTTPS (policies/security.kmd)

CPF/CNPJ check-digit é obrigatório — validar só o formato (000.000.000-00) aceita 111.111.111-11 e afins. O dígito verificador (mód-11) é a regra real.

R4 — Contrato de erro de validação

Falha de validação é um erro de classe VL (errors/taxonomy.kmd §R1), severity: error, retryable: false com recovery: "fix_field:<name>" (taxonomy.kmd §R4 conditional). O envelope (errors/model.kmd) deve popular o array fields:

{
  "error_id": "KFORM-VL-422-001",
  "error_category": "VL",
  "severity": "error",
  "retryable": false,
  "recovery": "fix_field:cpf",
  "fields": [
    {"field": "cpf",   "rule": "check-digit", "message": "CPF inválido."},
    {"field": "email", "rule": "required",    "message": "Informe o e-mail."}
  ]
}
  • Um envelope VL sem fields é violação de contrato

    (model.kmd §R3.6 / audit model.kmd §R7.4).

  • message por campo é humanizada (user-facing-messages.kmd); o

    rule é o identificador máquina-legível (de R1).

  • Validação reporta todos os campos inválidos de uma vez (não falha no

    primeiro) — UX de formulário.

R5 — Audit determinístico

data-validation-audit.sh (advisory), via /k-housekeep:

  1. Endpoint que aceita CPF/CNPJ sem validar check-digit (só formato) → error.
  2. Regra de validação só no cliente, ausente no servidor → error (R2.1).
  3. Lógica de validação duplicada client/server a partir de fontes distintas

    (em vez de schema único) → warning (R2.3).

  4. Erro VL emitido sem array fields → warning (cross model.kmd §R7.4).
  5. url aceitando http:// (não-HTTPS) → error (policies/security.kmd).

Não-escopo

  • Tipo/storage do valor — specs/data/field-types.kmd.
  • Máscara de apresentação — specs/data/masks.kmd.
  • Texto das mensagens — specs/errors/user-facing-messages.kmd.
  • Linguagem de schema — JSON Schema draft 2020-12 (extract-RFC-001).
  • Unicidade/isolamento cross-tenant — specs/multi-tenancy/contract.kmd.
  • specs/errors/taxonomy.kmd — classe VL, severidade, retryability.
  • specs/errors/model.kmd — array fields do envelope (§R2, §R3.6).
  • specs/components/text-fields.kmd — estados visuais de validade.