Se você já passou algum tempo trabalhando com desenvolvimento web, APIs ou arquivos de configuração, com certeza já se deparou com JSON. Ele aparece em todo lugar, desde as respostas que seu navegador recebe ao carregar um feed do Twitter até os arquivos de configuração do VS Code. Mas o que é JSON exatamente e por que ele se tornou o formato padrão para transportar dados pela internet?
Este guia apresenta o JSON do zero. Nenhum conhecimento prévio é necessário.
O que significa JSON
JSON é a sigla para JavaScript Object Notation. Douglas Crockford popularizou o formato no início dos anos 2000, baseando-o em um subconjunto da sintaxe de objetos literais do JavaScript. Apesar do nome, o JSON é independente de linguagem. Você pode ler e escrever JSON em Python, Java, Go, Ruby, C#, PHP e em praticamente todas as outras linguagens de programação em uso atualmente.
A grande sacada por trás do JSON foi a simplicidade. O XML era o formato dominante de troca de dados na época, e era verboso. O JSON ofereceu uma alternativa mais leve, que os humanos conseguiam ler sem apertar os olhos e que as máquinas conseguiam interpretar sem muito esforço.
Um primeiro olhar sobre o JSON
Aqui está um documento JSON mínimo:
{
"name": "Alice",
"age": 30,
"isStudent": false
}
É só isso. As chaves envolvem o objeto, as chaves de cada par são strings entre aspas duplas e os valores vêm depois de dois-pontos. Vírgulas separam cada par chave-valor. Se você já escreveu um objeto JavaScript, isso parece familiar, mas existem algumas diferenças importantes que veremos em breve.
Os seis tipos de dados
O JSON suporta exatamente seis tipos de valores. Nem mais, nem menos.
Strings
Strings são envolvidas por aspas duplas. Aspas simples não são permitidas, o que confunde quem vem do Python ou do JavaScript, onde as aspas simples funcionam sem problemas.
{
"greeting": "Hello, world!",
"emoji": "Totally valid ✔"
}
Você pode incluir caracteres especiais usando escapes com barra invertida: \" para aspas literais, \\ para uma barra invertida, \n para quebra de linha e \t para tabulação.
Numbers
Números podem ser inteiros ou de ponto flutuante. O JSON não faz distinção entre os dois. A notação científica é permitida.
{
"temperature": 22.5,
"population": 7900000000,
"planckConstant": 6.626e-34
}
Um detalhe para ficar atento: o JSON não suporta NaN, Infinity nem zeros à esquerda como 007. Eles vão causar um erro de parsing.
Booleans
Apenas true e false, em minúsculas. Não True, não TRUE, não 1.
{
"isActive": true,
"isDeleted": false
}
Null
O valor null representa a ausência intencional de um valor. Mais uma vez, somente em minúsculas.
{
"middleName": null
}
Objects
Objetos são coleções de pares chave-valor envolvidas por chaves. As chaves de cada par precisam ser strings. Os valores podem ser qualquer um dos seis tipos, inclusive outros objetos.
{
"user": {
"id": 42,
"profile": {
"bio": "Likes coffee",
"location": "Tokyo"
}
}
}
Objetos podem ser aninhados tão profundamente quanto você precisar, embora um JSON muito aninhado fique difícil de ler. Um JSON Formatter ajuda quando você está encarando uma parede de dados aninhados.
Arrays
Arrays são listas ordenadas de valores envolvidas por colchetes. Os valores não precisam ser do mesmo tipo, embora na prática geralmente sejam.
{
"colors": ["red", "green", "blue"],
"matrix": [[1, 2], [3, 4]],
"mixed": [42, "hello", null, true]
}
Arrays e objetos podem ser combinados livremente. Um array de objetos é um dos padrões mais comuns que você verá em JSON do mundo real:
{
"employees": [
{ "name": "Alice", "role": "Engineer" },
{ "name": "Bob", "role": "Designer" }
]
}
Onde o JSON aparece na prática
Respostas de API
Esse é o caso mais importante. Quando seu navegador ou aplicativo móvel se comunica com um servidor, a resposta é quase sempre JSON. Se você abrir as ferramentas de desenvolvedor do navegador e olhar a aba de rede, verá JSON indo e voltando o tempo todo.
Uma resposta de API típica pode ter esta aparência:
{
"status": "ok",
"data": {
"userId": 1,
"posts": [
{
"id": 101,
"title": "First Post",
"published": true
}
]
}
}
APIs REST, APIs GraphQL, payloads de webhook: todos usam JSON por padrão. O formato é tão dominante que muitos desenvolvedores nunca precisaram lidar com APIs baseadas em XML.
Arquivos de configuração
package.json em projetos Node.js, tsconfig.json para TypeScript, settings.json no VS Code, .eslintrc.json para o ESLint: a lista continua. O JSON se tornou uma escolha natural para arquivos de configuração porque toda linguagem já tinha um parser de JSON embutido.
Dito isso, o JSON tem uma limitação notável para configuração: ele não suporta comentários. Esse é um dos motivos pelos quais existem formatos como YAML e JSONC (JSON with Comments). Se você tem curiosidade sobre como o YAML se compara, dê uma olhada em YAML vs JSON: escolhendo o formato certo.
Armazenamento e troca de dados
Muitos bancos de dados NoSQL, como MongoDB e CouchDB, armazenam documentos em JSON ou em um formato binário semelhante ao JSON (BSON). Consultas e respostas do Elasticsearch são em JSON. Ferramentas de agregação de logs costumam trabalhar com linhas de log no formato JSON, porque são fáceis de interpretar programaticamente.
Quando dois sistemas precisam trocar dados, o JSON é a escolha padrão, a menos que haja um motivo específico para usar outra coisa. Ele é legível o suficiente para depuração, compacto o suficiente para transferência em rede e tem suporte universal.
Conversão de planilhas e dados tabulares
Se você trabalha com dados que começam a vida em uma planilha, exportados como CSV, talvez precise convertê-los para JSON para uso em uma API ou aplicação. As estruturas são bem diferentes, então entender os dois formatos ajuda. Veja O que é CSV para um olhar mais detalhado sobre o lado do CSV.
Regras que pegam as pessoas de surpresa
O JSON parece simples, e ele é, mas existem algumas regras que causam erros se você escreve à mão.
Vírgulas finais não são permitidas
Isto é JavaScript válido, mas JSON inválido:
{
"a": 1,
"b": 2,
}
Aquela vírgula depois de "b": 2 vai causar um erro de parsing. Todo parser de JSON vai rejeitá-la.
As chaves precisam ser strings entre aspas duplas
Em JavaScript, você pode escrever { name: "Alice" } sem colocar a chave entre aspas. O JSON exige { "name": "Alice" }. Aspas simples também não funcionam.
Sem comentários
Não existe sintaxe de comentário em JSON. Nem //, nem /* */, nem #. Se você precisa adicionar notas a um arquivo JSON, ou usa um formato diferente, ou adiciona uma chave fictícia como "_comment", embora isso seja uma gambiarra, e não uma solução de verdade.
O documento precisa ter uma única raiz
Um documento JSON precisa ser um único valor no nível superior. Normalmente é um objeto ou um array, mas tecnicamente uma string, um número, um booleano ou null isolado também são JSON válido.
O que você não pode fazer é ter dois objetos no nível superior:
{ "a": 1 }
{ "b": 2 }
Isso não é JSON válido. Se você precisa de vários objetos, coloque-os dentro de um array.
Para um mergulho mais profundo nessas regras com mais exemplos, confira o guia de sintaxe do JSON.
Trabalhando com JSON no código
Toda linguagem popular tem suporte a JSON embutido ou na biblioteca padrão.
Em JavaScript e TypeScript:
// Parse a JSON string into an object
const data = JSON.parse('{"name": "Alice", "age": 30}');
// Convert an object to a JSON string
const json = JSON.stringify(data, null, 2);
Os argumentos null, 2 passados para stringify adicionam indentação, deixando a saída legível para humanos. Sem eles, você obtém uma única linha compactada, o que é ótimo para transferência em rede, mas péssimo para leitura.
Em Python:
import json
data = json.loads('{"name": "Alice", "age": 30}')
text = json.dumps(data, indent=2)
O padrão é o mesmo em todo lugar: fazer o parsing de uma string para uma estrutura de dados nativa, manipulá-la e serializá-la de volta para uma string.
Formatando e validando JSON
Quando você recebe um bloco de JSON minificado de uma resposta de API ou de um arquivo de log, pode ser quase impossível de ler. Um formatter adiciona indentação e quebras de linha para que você consiga enxergar a estrutura de fato.
Você pode fazer isso no código, como mostrado acima, ou usar uma ferramenta como o JSON Formatter para colar o JSON bruto e obter uma versão limpa e indentada na hora. Ele também detecta erros de sintaxe, o que é útil quando você está depurando uma resposta malformada.
Para dicas sobre como manter seu JSON limpo e legível, veja dicas de formatação de JSON.
JSON vs outros formatos
O JSON não é o único formato de dados por aí, e nem sempre é a melhor escolha.
O YAML é mais amigável para humanos em arquivos de configuração porque suporta comentários e usa indentação em vez de chaves. Manifestos do Kubernetes, workflows do GitHub Actions e arquivos do Docker Compose usam YAML. O custo disso é que as regras de indentação do YAML podem ser sensíveis, e ele tem alguns comportamentos surpreendentes em relação à coerção de tipos.
O XML é mais verboso, mas suporta atributos, namespaces e schemas. Ele ainda é comum em sistemas corporativos, APIs SOAP e alguns formatos de documento.
O CSV é ótimo para dados tabulares, mas não tem conceito de aninhamento nem de tipos de dados. Tudo é uma string, a menos que a aplicação que consome os dados decida o contrário.
Protocol Buffers e MessagePack são formatos binários mais eficientes que o JSON para transferência em rede, mas não são legíveis para humanos.
Para a maioria das tarefas de desenvolvimento web, o JSON atinge o ponto ideal entre legibilidade, simplicidade e suporte universal.
Referência rápida
Aqui está um documento JSON completo que demonstra todos os tipos de dados:
{
"string": "Hello",
"number": 42,
"float": 3.14,
"boolean": true,
"nullValue": null,
"array": [1, 2, 3],
"object": {
"nested": "value"
}
}
Isso cobre todos os seis tipos. Se você consegue ler isto, consegue ler qualquer documento JSON: o resto é apenas composição.
Próximos passos
Agora que você entende o básico, aqui estão alguns caminhos para seguir:
- Leia o guia de sintaxe do JSON para uma referência completa sobre como escrever JSON correto, incluindo todos os tipos de dados e os padrões de aninhamento mais comuns.
- Experimente o JSON Formatter para colar um JSON do mundo real e vê-lo devidamente indentado.
- Explore YAML vs JSON se estiver decidindo qual formato usar em um arquivo de configuração.
- Confira as dicas de formatação de JSON para conselhos práticos sobre como manter seu JSON limpo em produção.
O JSON é uma daquelas tecnologias que recompensam quem entende os fundamentos. A sintaxe é pequena o suficiente para ser aprendida em uma tarde, e esse conhecimento dá retorno toda vez que você depura uma resposta de API, edita um arquivo de configuração ou monta um pipeline de dados.