Eu Amo e Odeio o Json

Usar JSON como formato de configuração é um erro.

Sim, um erro. Não uma preferência. Não um estilo. Um erro arquitetural.

Essa frase costuma incomodar porque JSON funciona. E quando algo funciona, a indústria tem uma tendência enorme a parar de questionar se aquilo também faz sentido.

JSON é um sucesso absoluto como formato de transporte. Ele é previsível, determinístico, fácil de parsear e praticamente universal. Entre máquinas, ele é excelente. O problema começa quando decidimos que essas mesmas qualidades o tornam adequado para ser escrito, lido, versionado e mantido por humanos.

Não tornam.

JSON é rígido, verboso e deliberadamente limitado. Ele não aceita comentários, não comunica intenção, não oferece contexto e não tolera erro. Essas características são virtudes quando o objetivo é interoperabilidade. Elas viram atrito puro quando o objetivo é expressar regras, configurações ou estruturas de domínio.

Ainda assim, seguimos usando JSON como formato de configuração, como DSL improvisada e como camada de autoria em sistemas onde humanos passam horas lendo e escrevendo aquilo. Funciona? Funciona. Mas funciona mal - e o fato de termos normalizado esse sofrimento não o transforma em boa engenharia.

Este texto não é um ataque ao JSON. É um ataque à insistência em usar uma ferramenta correta no lugar errado, e depois fingir surpresa quando a experiência para quem escreve é miserável.

Por que JSON venceu

JSON não venceu por ser bonito, elegante ou expressivo. Ele venceu porque é chato, limitado e previsível — e isso é uma qualidade enorme quando o problema é comunicação entre sistemas.

É um formato pequeno, fechado, sem ambiguidades sintáticas relevantes, fácil de implementar e difícil de interpretar errado. Ele reduz drasticamente o espaço para criatividade, e isso é exatamente o que você quer quando dois processos que não se conhecem precisam trocar dados sem conversar sobre intenção, contexto ou significado implícito.

Do ponto de vista de comunicação máquina-para-máquina, JSON é quase ideal. Ele força estruturas simples, não permite atalhos estranhos, não carrega semântica implícita e não tenta ser inteligente. É basicamente um envelope previsível de dados primitivos. Máquinas adoram isso. Compiladores adoram isso. Infraestrutura adora isso.

Quando alguém diz “minha API fala JSON”, todo mundo sabe exatamente o que isso significa. Não existe surpresa, não existe interpretação criativa, não existe “ah, mas nesse caso aqui…”. Existe um contrato. E contratos rígidos são excelentes quando ninguém quer negociar nada em tempo de execução.

Como formato de transporte, JSON merece todo o respeito que tem.

Onde tudo começa a dar errado

O problema começa quando alguém olha para esse mesmo formato, claramente projetado para comunicação máquina-para-máquina, e decide que ele também é uma boa ideia para autoria humana.

Isso normalmente não nasce de má fé. Nasce de preguiça arquitetural. O raciocínio costuma ser simples: se o sistema consome JSON, vamos fazer as pessoas escreverem JSON. Parece lógico. É também uma péssima ideia.

JSON exige precisão sintática absoluta para expressar até a menor intenção. Uma vírgula fora do lugar, uma aspa esquecida, um colchete mal fechado, e tudo quebra. Não existe “quebrar um pouco”. Existe erro de parse e fim de conversa.

Esse comportamento é aceitável para máquinas. Para humanos, é simplesmente hostil - e isso vindo de alguém que gosta de tipagem forte e contratos explícitos.

JSON é estruturalmente hostil a humanos

Não é uma questão de gosto. É estrutural.

JSON não permite comentários. JSON não permite trailing commas em sua forma canônica. JSON não permite atalhos. JSON não permite relaxamento sintático. JSON não permite contexto. JSON não permite intenção - apenas estrutura.

Isso força quem escreve a pensar constantemente em sintaxe, não em significado. Em vez de raciocinar sobre o domínio, você está validando mentalmente se fechou todos os colchetes, se usou aspas duplas em tudo, se não esqueceu nenhuma vírgula. É um imposto cognitivo alto para uma tarefa que normalmente já é complexa por natureza.

Quando você vê um JSON grande escrito à mão, aquilo raramente transmite clareza. Transmite resistência. Transmite que alguém sofreu ali.

Configuração em JSON é um erro que normalizamos

Arquivos de configuração em JSON são provavelmente o exemplo mais comum dessa disfunção. Eles existem aos montes, funcionam, e todo mundo aceita como “o jeito que é”. Isso não significa que seja um bom jeito.

Configuração é, por definição, algo que será lido, escrito, revisado, versionado e discutido por humanos. Ela carrega intenção, contexto e frequentemente precisa de comentários explicativos. JSON não oferece nada disso.

O resultado são arquivos verbosos, difíceis de revisar em pull requests, impossíveis de comentar adequadamente e cheios de convenções externas do tipo “essa chave aqui é opcional, mas só em tal cenário, explicado num README em outro lugar”.

Funciona. Mas funciona na força do ódio.

O argumento pró-JSON

“Mas JSON é simples. Todo mundo conhece.”

Sim, todo mundo conhece. Isso não significa que seja adequado. Esse é um argumento fraco.

Todo mundo conhece assembly também. Nem por isso escrevemos regras de negócio nele. Conhecimento não é critério de escolha de ferramenta. Adequação ao problema é.

JSON é simples para consumir, não para produzir. E essa diferença importa muito mais do que parece.

Formatos de autoria existem por um motivo

Quando você usa TypeScript, YAML, TOML, HCL ou qualquer DSL minimamente decente para definir estruturas complexas, a diferença é imediata. Esses formatos foram pensados para serem escritos, lidos e mantidos por pessoas.

Eles aceitam comentários. Permitem alguma flexibilidade. Comunicam melhor a intenção. Reduzem o custo cognitivo da escrita. E, mais importante, permitem que o humano pense primeiro no problema e só depois na representação.

O fato de muitos desses formatos eventualmente serem convertidos para JSON internamente não é coincidência. É arquitetura saudável.

O pipeline que evita sofrimento desnecessário

Em sistemas bem projetados, o fluxo costuma ser simples e previsível:

• O humano escreve algo expressivo, validável e confortável (muitas vezes tipado).

• A máquina valida, transforma e normaliza essa estrutura.

• JSON aparece apenas no momento em que precisa trafegar ou ser persistido como contrato entre sistemas.

Essa separação não é burocracia. É respeito pelos limites humanos.

• Se você está escrevendo configurações fortemente tipadas para uma máquina, TypeScript resolve muito bem.

• Se está escrevendo uma estrutura de configuração que precisa ser lida e mantida, YAML ou algo similar faz sentido.

• Se uma máquina precisa enviar dados para outra máquina, JSON é a escolha perfeita.

Quando você escreve uma API, por exemplo, você trabalha com objetos, tipos, validações e abstrações. O JSON nasce no final do processo, atravessa a rede, é parseado do outro lado e imediatamente deixa de existir como preocupação humana. Ninguém tocou nesse JSON diretamente — e isso é exatamente o ponto.

Esse padrão aparece repetidamente em ferramentas modernas porque ele funciona. Ele respeita as limitações humanas e explora as virtudes das máquinas. Forçar JSON desde o início é pular esse passo e jogar todo o custo em quem menos deveria pagar por ele.

Hater ou fã?

Eu continuo amando JSON onde ele faz sentido: transporte, contrato, serialização, comunicação entre sistemas. E continuo odiando JSON quando alguém espera que eu escreva, revise e mantenha estruturas complexas nele como se isso fosse uma experiência aceitável.

Não é birra.

Não é moda.

Não é elitismo técnico.

É só respeito básico por quem precisa lidar com o código.

JSON não precisa ser onipresente para continuar sendo valioso. Ele só precisa ficar no lugar certo.

E esse lugar, definitivamente, não é entre você e o teclado às duas da manhã.