Resultado do JSON Formatter do FormatArcResultado do JSON Formatter do FormatArc
Publicado: 2026-03-20Atualizado: 2026-05-16

Como Escrever JSON: Um Guia Completo de Sintaxe

Aprenda a forma correta de escrever JSON com exemplos para cada tipo de dado, padrões de aninhamento e erros comuns que você deve evitar.

A sintaxe do JSON cabe em uma ficha de fichário. São seis tipos de dados, duas estruturas de contêiner e um punhado de regras. É genuinamente só isso. Mas essa simplicidade é enganosa: as pessoas ainda cometem erros ao escrever JSON na mão, especialmente quando estão acostumadas com as regras mais flexíveis de JavaScript ou Python.

Este guia é uma referência completa da sintaxe do JSON. Todos os tipos de dados, todas as regras, muitos exemplos. Salve nos favoritos para a próxima vez que precisar escrever ou depurar JSON manualmente.

A gramática do JSON é definida oficialmente na RFC 8259 e na ECMA-404. As duas especificações concordam quanto à sintaxe; este guia cobre as mesmas regras com exemplos práticos e os erros que a maioria das pessoas comete ao escrever JSON na mão.

Se você é totalmente novo em JSON, comece por O que é JSON? Um guia para iniciantes e volte aqui para a referência detalhada de sintaxe.

O elemento raiz

Um documento JSON é um único valor. Esse valor geralmente é um objeto ou um array, mas a especificação permite qualquer um dos seis tipos no nível superior.

Documentos JSON válidos:

{"name": "Alice"}

[1, 2, 3]

"just a string"

42

true

null

Na prática, você quase sempre verá um objeto ou um array como raiz. APIs retornam objetos, feeds de dados retornam arrays de objetos e arquivos de configuração são objetos.

Strings

Strings são o tipo de valor mais comum no JSON, e são as que têm mais regras.

Aspas duplas são obrigatórias

Strings JSON devem ser envolvidas por aspas duplas. Não aspas simples. Não crases.

{ "correct": "hello" }

Todos estes são inválidos:

{ 'wrong': 'hello' }
{ `wrong`: `hello` }
{ wrong: "hello" }

O último exemplo — uma chave sem aspas — é JavaScript válido, mas não é JSON válido. Esse é provavelmente o erro mais comum que as pessoas cometem ao escrever JSON na mão.

Sequências de escape

Certos caracteres precisam ser escapados com uma barra invertida dentro das strings:

Sequência Significado
\" Aspas duplas
\\ Barra invertida
\/ Barra
\b Backspace
\f Form feed
\n Nova linha
\r Retorno de carro
\t Tab
\uXXXX Caractere Unicode

Exemplo:

{
  "path": "C:\\Users\\alice\\documents",
  "message": "She said \"hi\"",
  "newline": "Line one\nLine two"
}

Unicode

JSON é codificado em UTF-8 (ou UTF-16 ou UTF-32, embora UTF-8 seja predominante). Você pode incluir caracteres Unicode diretamente ou usar sequências de escape \u:

{
  "direct": "café",
  "emoji": "❤",
  "japanese": "東京"
}

Na maioria das vezes, você pode simplesmente digitar os caracteres diretamente. O escape \u é útil principalmente quando você precisa incluir caracteres difíceis de digitar ou que podem ser corrompidos por problemas de codificação de texto.

O que as strings não podem conter

Caracteres de controle brutos (de U+0000 até U+001F) precisam ser escapados. Você não pode colocar um caractere literal de tabulação ou de nova linha dentro de uma string JSON — use \t e \n em vez disso.

Numbers

Os numbers do JSON são diretos, mas há algumas restrições em comparação ao que o JavaScript permite.

Inteiros

{
  "positive": 42,
  "negative": -17,
  "zero": 0
}

Ponto flutuante

{
  "pi": 3.14159,
  "small": 0.001
}

Observe que .5 não é JSON válido. Você precisa escrever 0.5. O zero à esquerda é obrigatório.

Notação científica

{
  "avogadro": 6.022e23,
  "planck": 6.626e-34,
  "explicit": 1.0E+10
}

O e pode ser maiúsculo ou minúsculo. O expoente pode ter um sinal + ou -.

O que os numbers não podem ser

  • Sem zeros à esquerda: 007 é inválido. Use 7.
  • Sem hexadecimal: 0xFF é inválido. Use 255.
  • Sem octal: 0o17 é inválido. Use 15.
  • Sem NaN ou Infinity: esses não são valores JSON válidos. Se precisar representá-los, use null ou uma string como "NaN".
  • Sem ponto decimal final: 42. é inválido. Use 42 ou 42.0.

Considerações sobre precisão

A especificação do JSON não define limites de precisão para numbers, mas, na prática, a maioria dos parsers usa ponto flutuante de dupla precisão IEEE 754. Isso significa que inteiros maiores que 2^53 (9.007.199.254.740.992) podem perder precisão. Se você trabalha com inteiros muito grandes — como os snowflake IDs do Twitter — é prática comum transmiti-los como strings.

{
  "safe": 9007199254740991,
  "asString": "9007199254740993"
}

Booleans

Dois valores, em minúsculas:

{
  "active": true,
  "deleted": false
}

Não True, não TRUE, não 1, não "true". Apenas true e false.

Isso parece óbvio, mas causa erros quando as pessoas copiam valores do Python (que usa True e False com maiúsculas) ou do YAML (que aceita yes, no, on, off).

Null

Um valor, em minúsculas:

{
  "middleName": null
}

Não None (isso é Python), não nil (isso é Ruby), não undefined (isso é JavaScript). O JSON não tem o conceito de undefined — se uma chave não tem valor, você ou a define como null ou omite a chave por completo.

Objects

Objects são a estrutura central do JSON. São coleções não ordenadas de pares chave-valor.

Sintaxe básica

{
  "key": "value",
  "anotherKey": 42
}

Regras:

  • Chaves {} envolvem o object
  • As chaves precisam ser strings (entre aspas duplas)
  • Dois-pontos separam a chave do valor
  • Vírgulas separam os pares
  • Sem vírgula final após o último par

Objects vazios

{}

Perfeitamente válido. Representa um object sem propriedades.

Objects aninhados

Objects podem conter outros objects:

{
  "user": {
    "name": "Alice",
    "address": {
      "street": "123 Main St",
      "city": "Tokyo",
      "country": "Japan"
    }
  }
}

Não há limite de profundidade de aninhamento na especificação, embora estruturas muito profundas se tornem difíceis de ler e alguns parsers imponham limites práticos.

Ordenação das chaves

A especificação do JSON diz que objects são não ordenados. Isso significa que {"a": 1, "b": 2} e {"b": 2, "a": 1} são semanticamente equivalentes. Na prática, a maioria dos parsers preserva a ordem de inserção, mas você não deve depender da ordenação das chaves.

Chaves duplicadas

A especificação desencoraja chaves duplicadas, mas não as proíbe explicitamente. O comportamento varia conforme o parser — alguns usam o último valor, alguns o primeiro, alguns lançam um erro e uns poucos mantêm os dois. A regra do "último valor vence" é a mais comum, mas não é garantida.

{
  "name": "Alice",
  "name": "Bob"
}

O resultado de fazer o parsing desse documento depende da biblioteca: você pode obter "Alice", "Bob" ou um erro de parsing. Se você não consegue garantir a unicidade no produtor, valide a saída com o JSON Formatter — chaves duplicadas ficam visíveis quando você ordena ou formata os dados.

Arrays

Arrays são listas ordenadas de valores.

Sintaxe básica

[1, 2, 3, 4, 5]

Regras:

  • Colchetes [] envolvem o array
  • Vírgulas separam os valores
  • Sem vírgula final após o último valor
  • Os valores podem ser de qualquer tipo JSON

Arrays vazios

[]

Arrays de tipos mistos

O JSON permite arrays com tipos mistos:

[42, "hello", true, null, {"key": "value"}, [1, 2]]

Isso é válido, mas, na prática, arrays geralmente contêm valores do mesmo tipo. Um array de objects é o padrão mais comum.

Arrays de objects

Esta é a estrutura que você encontrará com mais frequência ao trabalhar com APIs e feeds de dados:

[
  {
    "id": 1,
    "name": "Alice",
    "email": "alice@example.com"
  },
  {
    "id": 2,
    "name": "Bob",
    "email": "bob@example.com"
  }
]

Cada object no array normalmente tem o mesmo conjunto de chaves, formando algo como uma tabela em que cada object é uma linha.

Padrões de aninhamento

O JSON do mundo real combina objects e arrays de várias maneiras. Aqui estão os padrões comuns.

Object contendo arrays

{
  "name": "Project Alpha",
  "tags": ["web", "api", "typescript"],
  "contributors": [
    { "name": "Alice", "role": "lead" },
    { "name": "Bob", "role": "developer" }
  ]
}

Array contendo objects aninhados

[
  {
    "department": "Engineering",
    "teams": [
      {
        "name": "Frontend",
        "members": ["Alice", "Bob"]
      },
      {
        "name": "Backend",
        "members": ["Charlie", "Diana"]
      }
    ]
  }
]

Estruturas profundamente aninhadas

{
  "company": {
    "departments": [
      {
        "name": "Engineering",
        "teams": [
          {
            "name": "Frontend",
            "projects": [
              {
                "name": "Dashboard",
                "status": "active",
                "milestones": [
                  { "name": "v1.0", "date": "2026-06-01" }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Isso é válido, mas começa a ficar difícil de ler. Quando você se deparar com JSON profundamente aninhado, um JSON Formatter ajuda aplicando uma indentação consistente.

Espaços em branco

O JSON ignora os espaços em branco entre os tokens. Todos estes são equivalentes:

Compacto:

{"name":"Alice","age":30}

Legível:

{
  "name": "Alice",
  "age": 30
}

Com excesso de espaços:

{
    "name"  :  "Alice"  ,
    "age"   :  30
}

Para transmissão e armazenamento, o JSON compacto economiza banda. Para leitura e edição, o JSON indentado é muito mais fácil de trabalhar. A maioria das ferramentas e bibliotecas permite escolher o formato.

Erros comuns

Estes são os erros que aparecem com mais frequência ao escrever JSON na mão.

Vírgulas finais

{
  "a": 1,
  "b": 2,
}

Aquela vírgula final depois de "b": 2 é inválida. JavaScript e muitas outras linguagens a permitem, mas o JSON não. Esse é provavelmente o erro de sintaxe JSON mais comum de todos.

Aspas simples

{'name': 'Alice'}

Inválido. O JSON exige aspas duplas tanto para as chaves quanto para os valores de string.

Chaves sem aspas

{name: "Alice"}

Inválido. As chaves precisam ser strings entre aspas duplas.

Comentários

{
  // this is not allowed
  "name": "Alice"
}

O JSON não tem sintaxe de comentário. Nem //, nem /* */, nem #. Se você precisar de JSON com comentários, considere JSONC ou JSON5, mas saiba que os parsers JSON padrão vão rejeitá-los.

Undefined e NaN

{
  "value": undefined,
  "result": NaN
}

Nem undefined nem NaN são valores JSON válidos. Use null para valores ausentes e uma string ou null para resultados não numéricos.

Valor único sem aspas

hello

Uma string solta sem aspas não é JSON válido. Ela precisaria ser "hello".

Para mais informações sobre como diagnosticar e corrigir esses erros, veja Soluções para o JSON Parse Error. Quando você está consertando JSON na mão, colar no JSON Formatter mostra a posição do erro com um número de linha, para que você identifique o caractere quebrado num relance.

Validando seu JSON

Quando você escreve JSON na mão, erros acontecem. Uma vírgula faltando, uma aspa a mais, uma vírgula final — tudo isso causa erros de parsing que podem ser frustrantes de rastrear em um documento grande.

O JSON Formatter vai validar seu JSON e apontar erros de sintaxe. Cole seu JSON e, se houver um erro, você verá exatamente o que deu errado.

Você também pode validar pela linha de comando:

# Using Python
python3 -m json.tool < file.json

# Using jq
jq . file.json

Os dois imprimem o JSON formatado em caso de sucesso ou uma mensagem de erro em caso de falha. Para formatar JSON retornado de chamadas de API com curl, veja Como formatar JSON do curl.

Convenções de formatação do JSON

Embora a sintaxe do JSON seja fixa, existem convenções que tornam o JSON mais fácil de trabalhar:

  • Use indentação de 2 espaços (a convenção mais comum)
  • Mantenha as chaves em uma ordem consistente entre objects semelhantes
  • Use camelCase ou snake_case para os nomes das chaves, mas seja consistente
  • Evite estruturas profundamente aninhadas quando um design mais plano funcionar

Para mais informações sobre essas convenções, veja Dicas de formatação de JSON.

Referência rápida

Todo valor JSON válido se encaixa em uma destas categorias:

Tipo Exemplo Observações
String "hello" Aspas duplas obrigatórias
Number 42, 3.14, 1e10 Sem hexadecimal, sem zeros à esquerda
Boolean true, false Apenas minúsculas
Null null Apenas minúsculas
Object {"key": "value"} As chaves precisam ser strings
Array [1, 2, 3] Ordenado, tipos mistos permitidos

Essa é a linguagem inteira. Tudo que você verá em um documento JSON é alguma combinação desses seis tipos.

Perguntas frequentes

Posso escrever comentários em JSON?

Não. //, /* */ e # são todos inválidos no JSON padrão. Se você precisar de comentários em um arquivo de configuração, use um superconjunto como JSONC ou JSON5, ou adote uma convenção como chaves "_comment": "...". Veja Como adicionar comentários ao JSON para as quatro soluções alternativas mais comuns.

Vírgulas finais são permitidas em JSON?

Não. Uma vírgula após o último elemento de um array ou object é um erro de sintaxe em praticamente todo parser JSON. Literais de JavaScript e Python aceitam vírgulas finais, então é um deslize comum ao colar a partir do código-fonte.

As chaves do JSON realmente precisam de aspas duplas?

Sim. As chaves do JSON precisam ser strings envolvidas por aspas duplas. A forma de chave sem aspas {name: "Alice"} é JavaScript válido, mas JSON inválido. Aspas simples 'name' também não são permitidas.

Como localizo rapidamente um erro de parsing de JSON?

Cole o JSON no JSON Formatter — ele destaca a linha que está falhando. Pela linha de comando, python3 -m json.tool < file.json ou jq . file.json também informam o número da linha. Para causas e correções comuns, veja Soluções para o JSON Parse Error.

Próximos passos