Data field types

mandatory

Catálogo canônico dos tipos de dado de campo na Koder Stack — o conjunto fechado de tipos primitivos e semânticos (string, text, int, decimal, bool, date, datetime, uuid, enum, email, phone, money, cpf, cnpj, cep, url, json, binary-ref) com sua representação canônica de armazenamento, faixa/limite default e regras de preenchimento. Base para `specs/data/masks.kmd` (apresentação) e `specs/data/validation.kmd` (regras). Não redefine conceitos já-com-dono: config é `specs/koder-toml/`, schema-language é JSON Schema (extract-RFC-001), naming de coluna é `specs/code/naming.kmd`, isolamento é `specs/multi-tenancy/contract.kmd`.

Facet Data do Koder Design. Define o que um valor é e como ele é armazenado. A máscara de apresentação é specs/data/masks.kmd; as regras (requiredformatlength) são specs/data/validation.kmd; a linguagem de schema (JSON Schema draft 2020-12) é a de rfcs/extract-RFC-001-foundations.kmd — esta spec mapeia seus tipos a essa linguagem, não a substitui.

Applicability

Todo campo de dado que um componente Koder modela, persiste, valida, exibe ou trafega — schemas de DB, payloads de API, campos de formulário, parâmetros de config-de-dado. Não se aplica a config de módulo (koder.toml → specs/koder-toml/) nem a env vars (policies/environments.kmd).

R1 — Tipos primitivos

Representação canônica de armazenamento (o wire/DB), independente de apresentação:

Tipo Armazenamento canônico Notas
string UTF-8, single-line, ≤ 255 chars default Sem n; trim de borda no input
text UTF-8, multi-line, sem limite default n permitido
int inteiro com sinal 64-bit Faixa explícita quando menor
decimal string decimal de precisão fixa Nunca float p/ valores exatos (ver money)
bool true/false Ausência ≠ false salvo regra explícita
date ISO 8601 date YYYY-MM-DD Sem timezone
datetime ISO 8601 com timezone 2026-04-17T15:42:30-03:00 Sempre com offset; armazenar UTC, exibir local
uuid UUIDv7 (time-ordered) canônico lowercase UUIDv7 default p/ chaves (índice sequencial)
enum string de conjunto fechado Valores em snake_case; documentar o conjunto
json objeto JSON validado por schema Schema declarado (extract-RFC-001)
binary-ref referência ao object store, não os bytes Bytes vão no plano de objetos (stack-RFC-006), nunca inline

R2 — Tipos semânticos (BR + comuns)

Tipos com regra de domínio. Armazenamento normalizado (sem máscara); a apresentação fica em masks.kmd; a validação em validation.kmd.

Tipo Armazenamento canônico Apresentação Validação
email lowercase, normalizado RFC 5321 como digitado validation.kmd
phone ISO E.164 (+5511912345678) locale (masks.kmd) libphonenumber (specs/components/phone-input.kmd)
money decimal minor units + currency ISO 4217 masks.kmd (R$ 1.234,56) ≥ 0 salvo regra
cpf 11 dígitos, sem máscara (12345678901) 123.456.789-01 (masks.kmd) dígitos verificadores (validation.kmd)
cnpj 14 dígitos, sem máscara (12345678000190) 12.345.678/0001-90 dígitos verificadores
cep 8 dígitos, sem máscara (01310100) 01310-100 formato + (opcional) lookup
url absoluta, normalizada, HTTPS only (policies/security.kmd) como armazenada scheme/host
percent decimal 0–100 (ou 0–1, declarar qual) 12,5% faixa

Regra de ouro de armazenamento: documento/identificador brasileiro é armazenado como dígitos puros (a máscara é só apresentação). Isso evita o bug clássico de comparar 123.456.789-01 ≠ 12345678901.

R3 — Regras de preenchimento

  1. Normalizar no input, não no output — strip de máscara, trim, lowercase

    (onde aplicável) acontecem uma vez, ao entrar; o storage guarda a forma canônica. A máscara é reaplicada só na exibição (masks.kmd).

  2. Nullable é explícito — um campo é obrigatório ou opcional por decisão

    declarada (validation.kmd §required), nunca por acidente de schema.

  3. Default declarado — se há valor default, ele é parte do schema, não

    do código de UI.

  4. Limite default — string ≤ 255; text sem limite; faixas numéricas

    explícitas quando não-64-bit. Ultrapassar é erro de classe VL (taxonomy.kmd §R1).

  5. Sufixo de unidade no nome — campos com unidade carregam a unidade no

    nome (timeout_ms, size_bytes, price_cents) — alinhar com specs/code/naming.kmd. Esta spec não redefine naming; cross-link.

  6. Tempo é UTC no storage — datetime sempre armazenado em UTC com

    offset preservado da origem quando relevante; exibição converte ao local.

R4 — Mapeamento para JSON Schema

A linguagem de schema canônica é JSON Schema draft 2020-12 (rfcs/extract-RFC-001-foundations.kmd). Esta tabela mapeia os tipos Koder às construções JSON Schema (não inventa schema-language nova):

Tipo Koder JSON Schema
string {"type":"string","maxLength":255}
int {"type":"integer"}
decimal/money {"type":"string","pattern":"^-?\d+(\.\d+)?$"}
date {"type":"string","format":"date"}
datetime {"type":"string","format":"date-time"}
uuid {"type":"string","format":"uuid"}
email {"type":"string","format":"email"}
enum {"enum":[…]}
cpfcnpjcep {"type":"string","pattern":"^\d{11}$"} (etc.)

R5 — Audit determinístico

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

  1. Campo cpfcnpjcep/phone cujo storage contém caractere de máscara

    (.,-,/,(,),espaço) → error (deve ser dígitos puros / E.164).

  2. Valor monetário em float/double → error (usar decimal).
  3. datetime sem timezone offset → warning.
  4. UUID que não seja v7 em campo de chave nova → warning (índice não-sequencial).
  5. binary-ref com bytes inline em vez de referência ao object store → error.

Não-escopo

  • Naming de campo/coluna — specs/code/naming.kmd (snake_case, sufixos).
  • Linguagem de schema — JSON Schema draft 2020-12 (extract-RFC-001).
  • Config de módulo — specs/koder-toml/.
  • Storage backend / object plane — rfcs/stack-RFC-001-kdb-as-unified-data-plane.kmd

    (dados), rfcs/stack-RFC-006-object-storage-plane-and-trust-tiering.kmd (objetos), specs/multi-tenancy/contract.kmd (isolamento).

  • specs/data/masks.kmd — apresentação dos tipos semânticos.
  • specs/data/validation.kmd — regras (requiredformatlength/check-digit).
  • specs/components/phone-input.kmd — caso aplicado de phone.
  • specs/errors/taxonomy.kmd — erros de preenchimento são classe VL.