JSON (JavaScript Object Notation) é o formato de troca de dados mais utilizado na web moderna. Praticamente toda API REST retorna JSON, arquivos de configuração usam JSON, e bancos de dados NoSQL como MongoDB armazenam dados nesse formato. O Python oferece suporte nativo e extremamente poderoso para JSON através do módulo json, parte da biblioteca padrão.

Neste guia completo, você vai aprender tudo sobre manipulação de dados JSON com Python: desde a serialização básica com json.dumps() e json.loads() até técnicas avançadas como codificadores personalizados, validação com JSON Schema e integração com APIs REST. Vamos começar!

O Que é JSON?

JSON é um formato de texto leve para armazenar e transportar dados estruturados. Ele foi especificado originalmente por Douglas Crockford no JSON.org e posteriormente padronizado pela RFC 7159. Sua sintaxe é simples e legível tanto para humanos quanto para máquinas.

JSON suporta apenas seis tipos de dados:

  • String: sequência de caracteres entre aspas duplas
  • Number: inteiros ou decimais (ponto flutuante)
  • Boolean: true ou false
  • Null: valor nulo (null)
  • Array: lista ordenada de valores entre colchetes []
  • Object: coleção de pares chave/valor entre chaves {}
{
  "nome": "Python",
  "versao": 3.12,
  "paradigmas": ["Orientado a Objetos", "Funcional", "Imperativo"],
  "tipagem": "dinâmica",
  "open_source": true,
  "criador": null
}

Segundo a MDN Web Docs, JSON é um formato que se destaca por sua simplicidade e ubiquidade na web, sendo suportado nativamente por todas as linguagens de programação modernas.

O Módulo json do Python

O Python inclui o módulo json como parte de sua biblioteca padrão. Isso significa que você não precisa instalar nada, basta importá-lo e começar a usar. A documentação oficial do módulo json é o ponto de partida ideal para consultas aprofundadas.

import json

O módulo oferece quatro funções principais que formam a base de toda manipulação de JSON em Python:

  • json.dumps(): converte um objeto Python em uma string JSON
  • json.loads(): converte uma string JSON em um objeto Python
  • json.dump(): escreve um objeto Python diretamente em um arquivo JSON
  • json.load(): lê um arquivo JSON e o converte em objeto Python

json.dumps(): Serializando Python para JSON

A função json.dumps() (dump string) serializa um objeto Python em uma string JSON. A tabela de conversão segue o mapeamento padrão:

  • dict → Object {}
  • list, tuple → Array []
  • str → String
  • int, float → Number
  • True → true
  • False → false
  • None → null
import json

dados = {
"linguagem": "Python",
"criado_em": 1991,
"tipos": ["int", "float", "str", "list", "dict"],
"interpretada": True,
"autor": None
}


json_string = json.dumps(dados)
print(json_string)


Saída: {"linguagem": "Python", "criado_em": 1991, "tipos": ["int", "float", "str", "list", "dict"], "interpretada": true, "autor": null}

Observe como True se torna true e None se torna null automaticamente, seguindo o padrão JSON.

Parâmetros Avançados do dumps()

O json.dumps() oferece vários parâmetros para controlar a saída:

import json

dados = {"nome": "Python", "versao": 3.12, "features": ["simples", "poderoso"]}


indent, formata com indentação para legibilidade


print(json.dumps(dados, indent=2))


sort_keys, ordena as chaves alfabeticamente


print(json.dumps(dados, indent=2, sort_keys=True))


ensure_ascii, se False, permite caracteres Unicode


print(json.dumps({"nome": "João"}, ensure_ascii=False))


Saída: {"nome": "João"}


separators, personaliza separadores (remove espaços)


print(json.dumps(dados, separators=(",", ":")))


Saída: {"nome":"Python","versao":3.12,"features":["simples","poderoso"]}

O parâmetro ensure_ascii=False é essencial quando você trabalha com textos em português ou outros idiomas com acentos e caracteres especiais, como explica o tutorial da Real Python sobre JSON.

json.loads(): Convertendo JSON para Python

A função json.loads() (load string) faz o caminho inverso: recebe uma string JSON e a converte em um objeto Python.

import json

json_string = '{"nome": "Python", "versao": 3.12, "interpretada": true, "autor": null}'


dados = json.loads(json_string)
print(dados)


Saída: {'nome': 'Python', 'versao': 3.12, 'interpretada': True, 'autor': None}


print(type(dados))


Saída: <class 'dict'>

Perceba que a conversão respeita o mapeamento inverso: true vira True, null vira None, e strings JSON viram strings Python. O resultado é sempre um dicionário Python quando o JSON de origem é um objeto.

json.dump() e json.load(): Trabalhando com Arquivos

As funções json.dump() e json.load() (sem o "s" final) trabalham diretamente com arquivos, evitando a necessidade de strings intermediárias. Este tópico se complementa com o guia de Manipulação de Arquivos TXT, CSV e JSON.

import json

Escrevendo JSON em um arquivo


dados = {
"nome": "Python",
"ano": 1991,
"frameworks": ["Django", "Flask", "FastAPI"]
}


with open("dados.json", "w", encoding="utf-8") as arquivo:
json.dump(dados, arquivo, indent=2, ensure_ascii=False)


Lendo JSON de um arquivo


with open("dados.json", "r", encoding="utf-8") as arquivo:
dados_carregados = json.load(arquivo)


print(dados_carregados["nome"])  # Saída: Python

Sempre use a codificação utf-8 ao trabalhar com arquivos JSON para garantir a compatibilidade com caracteres acentuados e especiais.

Serializando Objetos Python Personalizados

Por padrão, o módulo json não sabe como serializar objetos de classes personalizadas. Tente executar o código abaixo e você receberá um TypeError:

import json

class Pessoa:
def init(self, nome, idade):
self.nome = nome
self.idade = idade


p = Pessoa("Ana", 30)
print(json.dumps(p))  # TypeError: Object of type Pessoa is not JSON serializable

Existem duas abordagens principais para resolver isso.

Método 1: Usando um Custom JSONEncoder

Crie uma subclasse de json.JSONEncoder e sobrescreva o método default(). A documentação oficial do JSONEncoder fornece todos os detalhes desta abordagem.

import json
from datetime import datetime

class Pessoa:
def init(self, nome, idade):
self.nome = nome
self.idade = idade


class CustomEncoder(json.JSONEncoder):
def default(self, obj):
if isinstance(obj, Pessoa):
return {"nome": obj.nome, "idade": obj.idade, "_tipo": "Pessoa"}
if isinstance(obj, datetime):
return obj.isoformat()
return super().default(obj)


p = Pessoa("Ana", 30)
data = datetime.now()
print(json.dumps({"pessoa": p, "data": data}, cls=CustomEncoder, indent=2))

Método 2: Usando Pydantic

O Pydantic é uma biblioteca que oferece validação de dados e serialização nativa para JSON. É amplamente utilizado com FastAPI e é a abordagem recomendada para projetos profissionais.

from pydantic import BaseModel

class Pessoa(BaseModel):
nome: str
idade: int


p = Pessoa(nome="Ana", idade=30)
print(p.model_dump_json(indent=2))


Saída: {"nome": "Ana", "idade": 30}

O método model_dump_json() do Pydantic já retorna uma string JSON válida, resolvendo a serialização de forma elegante e segura.

Lidando com Erros e Exceções

Ao trabalhar com dados JSON, especialmente aqueles vindos de fontes externas, é fundamental tratar erros de parsing. O módulo json levanta exceções específicas que devem ser capturadas:

import json

def processar_json(texto):
try:
dados = json.loads(texto)
return dados
except json.JSONDecodeError as e:
print(f"Erro ao decodificar JSON: {e}")
print(f"Posição do erro: linha {e.lineno}, coluna {e.colno}")
return None


JSON inválido


json_invalido = '{"nome": "Python", versao: 3.12}'
resultado = processar_json(json_invalido)


Saída: Erro ao decodificar JSON: ...


JSON válido


json_valido = '{"nome": "Python"}'
resultado = processar_json(json_valido)
print(resultado)


Saída: {'nome': 'Python'}

Sempre valide o JSON recebido antes de processá-lo. A combinação de try/except com json.JSONDecodeError garante que sua aplicação não quebre ao receber dados malformados.

Validação com JSON Schema

Para garantir que um JSON siga uma estrutura específica, você pode usar o JSON Schema. Esta especificação define contratos formais para a estrutura de documentos JSON, algo essencial em APIs e integrações entre sistemas.

from jsonschema import validate, ValidationError

schema = {
"type": "object",
"properties": {
"nome": {"type": "string", "minLength": 1},
"idade": {"type": "integer", "minimum": 0},
"email": {"type": "string", "format": "email"}
},
"required": ["nome", "email"]
}


dados_validos = {"nome": "Ana", "idade": 30, "email": "[email protected]"}
validate(instance=dados_validos, schema=schema)  # OK, não levanta exceção


dados_invalidos = {"nome": "", "email": "invalido"}
try:
validate(instance=dados_invalidos, schema=schema)
except ValidationError as e:
print(f"Erro de validação: {e.message}")

Embora a biblioteca jsonschema precise ser instalada separadamente (pip install jsonschema), ela é extremamente útil para validar payloads de API, arquivos de configuração e qualquer dado JSON que precise de uma estrutura previsível.

JSON e APIs REST

JSON é o formato padrão de entrada e saída da maioria das APIs REST modernas. Quando você faz uma requisição HTTP para uma API, a resposta quase sempre vem em JSON. Veja como consumir e enviar JSON usando a biblioteca requests:

import json
import requests

Consumindo uma API que retorna JSON


response = requests.get("https://api.github.com/users/python")
dados = response.json()  # Equivalente a json.loads(response.text)
print(f"Repositórios: {dados['public_repos']}")


Enviando JSON para uma API


payload = {"titulo": "Novo Post", "conteudo": "JSON com Python"}
headers = {"Content-Type": "application/json"}
response = requests.post(
"https://jsonplaceholder.typicode.com/posts",
data=json.dumps(payload),
headers=headers
)
print(response.json())

Para dominar completamente o consumo de APIs, confira o guia completo sobre Python Requests para requisições HTTP.

O FastAPI, um dos frameworks web mais populares do Python, usa o Pydantic para validar e serializar JSON automaticamente. A documentação do FastAPI sobre JSON Encoder mostra como o framework lida com tipos personalizados de forma transparente.

Boas Práticas e Performance

Ao trabalhar com JSON em Python, siga estas recomendações:

  • Sempre use ensure_ascii=False quando houver caracteres acentuados ou Unicode no conteúdo
  • Defina indent apenas em arquivos de configuração: em produção, omita para reduzir o tamanho dos dados trafegados
  • Use separators=(",", ":") em APIs para minimizar o payload JSON
  • Prefira Pydantic ou dataclasses para serialização de objetos em projetos maiores
  • Valide dados com JSON Schema quando a estrutura precisar ser garantida
  • Trate exceções com json.JSONDecodeError ao processar dados de fontes externas

Para projetos que exigem performance máxima, considere alternativas como orjson (escrito em Rust) ou ujson. O módulo nativo json do Python, porém, é suficiente para a grande maioria dos casos de uso e tem a vantagem de não exigir dependências externas.

O tutorial da W3Schools sobre Python JSON oferece exemplos adicionais e exercícios práticos para reforçar o aprendizado.

Conclusão

JSON e Python formam uma combinação poderosa e onipresente no desenvolvimento de software moderno. O módulo json da biblioteca padrão oferece todas as ferramentas necessárias para serializar, desserializar, ler e escrever dados JSON com apenas algumas linhas de código.

Neste guia, você aprendeu:

  • Os fundamentos do formato JSON e seus tipos de dados
  • As quatro funções principais: dumps(), loads(), dump(), load()
  • Como serializar objetos Python personalizados com JSONEncoder e Pydantic
  • Como tratar erros de parsing e validar estruturas com JSON Schema
  • Como integrar JSON com APIs REST usando a biblioteca requests
  • Boas práticas para performance e segurança

Com esse conhecimento, você está preparado para manipular dados JSON em qualquer projeto Python, seja uma aplicação web, um script de automação, uma API REST ou uma pipeline de dados. Para se aprofundar ainda mais, explore a documentação oficial e pratique com dados reais de APIs públicas.