O Que É JSON? Um Guia Simples, com Exemplos

JSON (JavaScript Object Notation) é um formato de texto simples para escrever dados estruturados — coisas como um cliente, uma encomenda ou uma lista de produtos — como pares de nomes e valores. É fácil de ler para as pessoas e fácil de gerar e interpretar para os programas. Quando as apps e os serviços trocam dados pela web, o JSON é de longe o formato mais comum.

Porque é que o JSON importa quando cria com IA

Vai encontrar JSON constantemente, mesmo que nunca escreva código:

• APIs. Quando os ecrãs da sua app carregam dados do backend, ou o seu backend chama um serviço de pagamentos, de email ou de IA, os dados normalmente viajam em JSON. Veja o que é uma API.
• Ficheiros de definições. Muitos ficheiros de configuração de projeto são JSON — por exemplo, o package.json, que lista as dependências de um projeto JavaScript.
• Bases de dados. O Postgres pode guardar JSON numa coluna (o tipo jsonb) para dados que não cabem em linhas e colunas simples. Veja o que é o Postgres.
• Respostas da IA. Quando quer que um modelo de IA devolva algo que um programa consiga usar — uma lista de etiquetas, campos extraídos de uma fatura — normalmente pede JSON.
• Mensagens de erro e registos. Muitos erros chegam em JSON, e lê-los é muitas vezes a forma mais rápida de perceber o que correu mal.

Saber ler JSON permite-lhe verificar o que a sua app recebeu de facto, reparar num campo em falta e descrever os problemas com precisão ao seu construtor de IA.

Uma analogia do dia a dia

Pense num formulário de papel: Nome: ____, Telefone: ____, Newsletter: ☐ sim ☐ não. Cada entrada é uma etiqueta com um valor ao lado. O JSON é esse formulário escrito como texto, num layout rígido que um computador consegue ler sem adivinhar. E, como os formulários, o JSON pode ter secções dentro de secções (um bloco de morada com rua, cidade e código postal) e listas (vários números de telefone).

Como é um JSON

Eis uma marcação num só bloco:

{
  "id": 5001,
  "customer": "Lena Park",
  "service": "Haircut",
  "startsAt": "2026-10-03T14:00:00Z",
  "price": 35.5,
  "paid": false,
  "notes": null,
  "extras": ["beard trim", "hot towel"],
  "contact": {
    "email": "lena@example.com",
    "phone": "+44 20 7946 0000"
  }
}

Como ler:

• As chavetas { } envolvem um objeto — um conjunto de pares nome/valor.
• Cada par é "nome": valor, separados por vírgulas.
• Os parênteses retos [ ] envolvem uma lista (um array) — uma lista ordenada.
• Objetos e listas podem estar uns dentro dos outros, como acontece com contact e extras.

Os seis tipos de valor

O JSON só tem seis tipos de valor. Esta lista curta é uma grande parte da razão por que funciona em todo o lado.

Não existe tipo de data. As datas escrevem-se como cadeias de texto, normalmente no formato ISO 8601 mostrado acima (2026-10-03T14:00:00Z, em que Z significa UTC). Combinar esse formato evita toda uma categoria de erros de fuso horário.

As regras rígidas (onde nascem os erros)

O JSON é menos tolerante do que parece. Todos os exemplos seguintes são inválidos:

{ name: "Lena" }            ← chave sem aspas duplas
{ 'name': 'Lena' }          ← aspas simples
{ "a": 1, "b": 2, }         ← vírgula a mais no fim
{ "a": 1 "b": 2 }           ← vírgula em falta
{ "a": 1 // comentário }    ← comentários não são permitidos

A maioria dos erros «Unexpected token» que vai ver é uma destas situações. Um validador ou formatador de JSON mostra-lhe a linha exata.

Exemplo prático: o JSON numa app

Um cliente marca um corte de cabelo numa app de salão. Eis onde aparece o JSON:

1. O formulário de marcação envia isto para o backend da app:

{ "service": "Haircut", "startsAt": "2026-10-03T14:00:00Z", "name": "Lena Park" }

1. O backend guarda a marcação na base de dados e responde com o estado 201 Created e:

{ "id": 5001, "status": "confirmed" }

1. Se a hora já estivesse ocupada, pode responder com o estado 409 Conflict e:

{ "error": "slot_taken", "message": "That time was just booked. Please pick another." }

A página lê status ou error e mostra a mensagem certa. Se, em vez disso, mostrar um ecrã em branco, abrir as ferramentas de programador do navegador (separador Network) mostra-lhe este JSON — muitas vezes, a pista mais rápida para descobrir o problema.

Termos-chave

Ideias erradas comuns

• «JSON é JavaScript.» Vem da sintaxe do JavaScript, mas não está ligado a nenhuma linguagem; Python, Java, C#, Go e as restantes conseguem lê-lo.
• «Números entre aspas são igualmente válidos.» "35" é um texto, não um número. Misturar os dois causa erros como "35" + "5" dar "355". O dinheiro costuma ser melhor guardado em cêntimos inteiros (3550) para evitar problemas de arredondamento.
• «JSON é seguro porque são apenas dados.» O JSON pode transportar qualquer coisa, incluindo segredos. Não ponha chaves de API em JSON enviado para o navegador.
• «Ponha tudo numa coluna JSON.» É prático para extras flexíveis, mas os dados que pesquisa, filtra ou cruza devem normalmente estar em colunas próprias.
• «A IA devolve sempre JSON válido.» Os modelos podem acrescentar texto extra ou estragar o formato. Muitos fornecedores oferecem um modo de saída estruturada; o seu código deve, ainda assim, verificar o que recebe.

O que pedir ao seu construtor de IA

• «Mostra-me um exemplo do JSON que este endpoint devolve.»
• «Devolve os erros em JSON com um código error e uma message legível por pessoas.»
• «Guarda as datas como cadeias ISO 8601 em UTC e converte para a hora local apenas no ecrã.»
• «Guarda os preços como cêntimos inteiros.»
• «Valida o JSON recebido no servidor e rejeita pedidos com campos em falta ou de tipo errado.»
• «Ao chamar o modelo de IA, pede JSON neste formato exato e verifica-o antes de o usar.»

JSON no Mythex

Não precisa de escrever JSON à mão no Mythex — descreve o que quer e o agente escreve o código que o envia e o lê. Ainda assim, é útil reconhecê-lo: quando algo falha, colar o erro de JSON no chat dá ao agente uma pista precisa. A receita de backend REST da documentação pede «erros JSON claros» desde o início, e a receita integrar qualquer API cobre a chamada a serviços externos. Para a visão geral, veja REST vs GraphQL e como depurar uma app criada com IA.

Perguntas