Tema: data-formats
-
Números de telefone E.164: o que armazenar e o que um validador não consegue saber
Armazene números de telefone como strings E.164 (sinal de mais, código do país e número nacional, no máximo 15 dígitos segundo o plano da ITU), nunca como inteiros; guarde a entrada original e a região usada na interpretação, valide com metadados de plano de numeração mantidos e lembre que uma verificação de sintaxe não diz se o número está atribuído, acessível ou pertence ao usuário.
-
Tags de idioma: BCP 47 em conteúdo e APIs
Tags de idioma combinam um código de idioma ISO 639 com subtags opcionais de escrita e região (de, de-CH, zh-Hant); use-as em declarações de idioma do conteúdo, no atributo lang do HTML e em filtros de API, e valide-as em vez de aceitar texto livre.
-
Nomes e capitalização consistentes nos campos JSON
Escolha uma única convenção de capitalização para os nomes de propriedades e aplique-a em toda parte: o guia de estilo JSON do Google e o ProtoJSON usam lowerCamelCase, e muitas APIs usam snake_case. Além da capitalização, use nomes significativos, enums como strings, timestamps como strings RFC 3339 e inteiros de 64 bits como strings.
-
Validando JSON com JSON Schema
O JSON Schema descreve a estrutura permitida de um documento (tipos, chaves obrigatórias, enumerações, formatos, limites) e permite validar entradas em qualquer linguagem antes de processá-las; convém declarar additionalProperties de forma explícita.
-
Números de ponto flutuante: por que 0.1 + 0.2 não é 0.3
O ponto flutuante binário representa a maioria das frações decimais apenas de forma aproximada, e por isso a aritmética acumula erros de arredondamento. Compare com tolerância, some com cuidado, use inteiros ou tipos decimais para dinheiro e contagens e imprima com dígitos suficientes para que o valor possa ser convertido de volta sem perdas (round-trip).
-
Como carregar YAML com segurança
Os loaders completos de YAML podem instanciar objetos arbitrários a partir de nós com tags; use sempre um loader seguro, fixe a semântica da versão do YAML e valide o resultado com um schema antes de usá-lo.
-
Noções básicas de vCard 4.0: o formato text/vcard para troca de contatos
Um vCard é um documento text/vcard em UTF-8 com BEGIN:VCARD, VERSION:4.0, um FN obrigatório e propriedades estruturadas opcionais (N, TEL, EMAIL, ADR, UID, REV) com parâmetros; os valores escapam vírgulas, pontos e vírgulas e barras invertidas, e as linhas de conteúdo são dobradas em no máximo 75 octetos. O jCard (RFC 7095) transporta o mesmo modelo em JSON.
-
Extração estruturada de documentos com JSON Schema, validação e tentativas limitadas
Defina o registro de destino como um JSON Schema com additionalProperties false, peça ao modelo exatamente essa forma, valide cada resposta com um validador de verdade, repita um número limitado de vezes incluindo o erro de validação no prompt e encaminhe a uma pessoa o que ainda falhar, em vez de adivinhar.
-
Dinheiro e outras quantidades exatas: use Decimal, não float
O ponto flutuante binário não consegue representar com exatidão a maioria das frações decimais, e por isso somas de preços acumulam erros; o módulo decimal oferece aritmética decimal exata com arredondamento explícito, e inteiros em unidades menores são uma alternativa.
-
Como escolher um formato de configuração: JSON, YAML ou TOML
JSON (RFC 8259) é estrito e legível em qualquer lugar, mas não admite comentários; YAML é fácil de ler, porém valores sem aspas têm o tipo inferido com base em padrões; TOML foi projetado para configuração, com comentários, tipos explícitos e tabelas. Quem edita o arquivo e o que o lê determinam a escolha, e todo formato precisa de validação contra um esquema após o parsing.
-
Colunas JSONB: para que servem e quando é melhor usar uma coluna comum
O jsonb guarda JSON já interpretado em formato binário, indexável com GIN e consultável com operadores de contenção e de caminho; serve para atributos esparsos, definidos externamente ou realmente variáveis. Dados com estrutura fixa, que exigem restrições, chaves estrangeiras ou atualizações por campo, e documentos grandes alterados com frequência pertencem a colunas comuns.
-
Fundamentos do armazenamento colunar: como um arquivo Parquet é organizado e por que leituras analíticas acessam menos dados
Um arquivo Parquet é uma sequência de row groups, cada um com um column chunk por coluna, e cada chunk é dividido em páginas, que são a unidade de codificação e compressão. Os metadados ficam no fim do arquivo, de modo que o leitor abre o rodapé, escolhe só as colunas necessárias e pula row groups e páginas com base nas estatísticas de mín./máx.; o layout por coluna é o que torna eficazes as codificações por dicionário e run-length.
-
Formatos de data e hora em APIs: ISO 8601 e RFC 3339
Transmita timestamps como strings RFC 3339 com offset explícito, datas como YYYY-MM-DD e durações como durações ISO 8601 ou segundos simples; nunca como texto dependente de locale nem como números ambíguos.
-
Mensagens de erro de API segundo a RFC 9457 (Problem Details)
A RFC 9457 define com `application/problem+json` um formato uniforme para respostas de erro de APIs HTTP: `type` como URI da classe de erro, `title`, `status`, `detail` e `instance`, extensível com campos próprios. Assim, clientes — incluindo agentes — podem ramificar a lógica pela classe de erro em vez de interpretar texto livre.
-
Convites iCalendar: UID, SEQUENCE e como acertar nos fusos horários
Um evento iCalendar é identificado pelo UID e revisado pelo SEQUENCE; seus horários são UTC, hora local com um TZID que aponta para um VTIMEZONE incorporado, ou flutuantes. Use hora local ancorada ao fuso para reuniões recorrentes, UTC para eventos únicos entre fusos e envie atualizações e cancelamentos com o METHOD do iTIP que o cliente receptor espera.
-
sort, uniq e comm: operações de conjuntos em texto que dependem de entrada ordenada
O uniq só colapsa duplicatas adjacentes, o comm exige que as duas entradas estejam ordenadas na mesma collation e a ordem do sort segue LC_COLLATE; execute esses pipelines com LC_ALL=C, escolha as opções de chave corretas (-n, -h, -V, -k, -t) e use comm -12 e comm -23 para interseções e diferenças.
-
Protocol Buffers: números de campo, campos desconhecidos e as regras para evoluir uma mensagem
No Protocol Buffers, o número do campo, e não o nome, identifica um campo no formato binário; por isso os números nunca devem mudar nem ser reutilizados. Adicionar campos é seguro no formato binário, remover só é seguro se o número nunca for reaproveitado (o que uma instrução reserved garante), leitores antigos preservam campos desconhecidos e ampliar int32 para int64 só é seguro sob certas condições. O ProtoJSON tem regras próprias e diferentes.
-
Como projetar identificadores públicos quando pessoas e agentes os copiam entre sistemas?
Pergunta em aberto: prefixos de tipo, dígitos verificadores, componentes ordenados por tempo, alfabetos sem caracteres parecidos e comprimento fixo resolvem, cada um, um problema dos identificadores lidos, digitados e colados por pessoas e agentes; quais combinações se sustentaram na prática e a que custo?
-
Datas e horas: UTC, ISO 8601 e fusos horários
Armazene instantes em UTC e troque-os como strings RFC 3339; no código, use apenas objetos com fuso horário e converta para um fuso IANA nomeado só na exibição; trate separadamente o cálculo de calendário e o cálculo de instantes.
-
Representação de grandezas físicas em JSON: valor, unidade e precisão em campos separados
Procedimento para transportar grandezas medidas ou calculadas em JSON: uma unidade canônica por tipo de grandeza, unidade no nome do campo quando ela é fixa e objeto com valor e unidade (código controlado) quando é mista, precisão declarada de forma explícita em vez de inferida pelo número de dígitos, e strings quando o valor decimal exato importa.
Legível por máquina: JSON