Como funciona
JSON mode é um parâmetro oferecido por provedores de LLM (OpenAI, Anthropic, Google, etc.) que instrui o modelo a responder apenas com JSON válido. O modelo não pode incluir texto livre antes ou depois do JSON.
A implementação varia: alguns provedores usam response_format: {type: "json_object"}, outros usam tool calling ou constrained decoding. O resultado é sempre um JSON sintaticamente válido, mas a estrutura interna (campos, tipos) não é garantida.
Por isso, JSON mode é o mínimo para integração. Para garantir que os campos e tipos correspondam ao esperado, use saída estruturada (structured output), que combina JSON mode com validação de schema.
Exemplo prático
Sem JSON mode, um modelo pode responder: "Claro! Aqui está o resultado: {\"nome\": \"João\", \"idade\": 30}. Espero que ajude!" O código que tenta parsear isso como JSON falha.
Com JSON mode, o modelo responde apenas: {"nome": "João", "idade": 30}. Sem texto extra, sem markdown, sem explicação. O JSON é válido e pode ser parseado diretamente.
Mas o modelo pode responder {"name": "João", "age": 30} em vez de {"nome": "João", "idade": 30}, se não houver instrução clara. JSON mode não controla os nomes dos campos.
Para que serve
Serve como primeiro passo para integrar LLMs a código: garante que a resposta seja parseável. É útil quando você precisa de JSON mas não quer a complexidade de definir um schema completo.
Diferença entre JSON mode e saída estruturada
JSON mode garante apenas que o output seja JSON válido. Saída estruturada garante que o output seja JSON válido E siga um schema específico (campos, tipos, obrigatoriedade). JSON mode é o piso; saída estruturada é o teto.