Data field types

data specs/data/field-types.kmd

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

When this spec applies

Primary triggers

All triggers

Spec — Data field types

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 (required/format/length) 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:

TipoArmazenamento canônicoNotas
stringUTF-8, single-line, ≤ 255 chars defaultSem \n; trim de borda no input
textUTF-8, multi-line, sem limite default\n permitido
intinteiro com sinal 64-bitFaixa explícita quando menor
decimalstring decimal de precisão fixaNunca float p/ valores exatos (ver money)
booltrue/falseAusência ≠ false salvo regra explícita
dateISO 8601 date YYYY-MM-DDSem timezone
datetimeISO 8601 com timezone 2026-04-17T15:42:30-03:00Sempre com offset; armazenar UTC, exibir local
uuidUUIDv7 (time-ordered) canônico lowercaseUUIDv7 default p/ chaves (índice sequencial)
enumstring de conjunto fechadoValores em snake_case; documentar o conjunto
jsonobjeto JSON validado por schemaSchema declarado (extract-RFC-001)
binary-refreferência ao object store, não os bytesBytes 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.

TipoArmazenamento canônicoApresentaçãoValidação
emaillowercase, normalizado RFC 5321como digitadovalidation.kmd
phoneISO E.164 (+5511912345678)locale (masks.kmd)libphonenumber (specs/components/phone-input.kmd)
moneydecimal minor units + currency ISO 4217masks.kmd (R$ 1.234,56)≥ 0 salvo regra
cpf11 dígitos, sem máscara (12345678901)123.456.789-01 (masks.kmd)dígitos verificadores (validation.kmd)
cnpj14 dígitos, sem máscara (12345678000190)12.345.678/0001-90dígitos verificadores
cep8 dígitos, sem máscara (01310100)01310-100formato + (opcional) lookup
urlabsoluta, normalizada, HTTPS only (policies/security.kmd)como armazenadascheme/host
percentdecimal 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 KoderJSON 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":[…]}
cpf/cnpj/cep{"type":"string","pattern":"^\\d{11}$"} (etc.)

R5 — Audit determinístico

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

  1. Campo cpf/cnpj/cep/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 (required/format/length/check-digit).
  • specs/components/phone-input.kmd — caso aplicado de phone.
  • specs/errors/taxonomy.kmd — erros de preenchimento são classe VL.

References