Spec — Data field validation

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 é assert/panic de code/error-handling.kmd §R2).

R1 — Tipos de regra (enum)

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):

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.

Cross-link

• 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.