# JSON — dados estruturados para aplicações, APIs e agentes de IA
> Guia prático completo sobre o formato JSON: regras de sintaxe, serialização via parse/stringify, integração com REST API, JSON Schema e saída estruturada para inteligência artificial.
## 1. O que é JSON e por que se tornou o padrão
O formato **JSON** (*JavaScript Object Notation*) é um padrão universal para a troca de dados estruturados entre servidores web, aplicações cliente, bases de dados e agentes de IA modernos.
Quando programas interagem entre si, transmitir informações em texto simples não estruturado é ineficiente:
> *"Olena Kovalchuk, 29 anos, Kyiv, assinatura premium ativa, habilidades: Python, SQL."*
Um humano entende facilmente essa descrição, mas um algoritmo gastaria recursos significativos apenas para reconhecer as entidades. No formato JSON, os mesmos dados são apresentados de forma rigorosa e determinística:
```json
{
"id": 1042,
"name": "Олена Ковальчук",
"age": 29,
"city": "Київ",
"isPremium": true,
"skills": ["Python", "SQL"]
}
```
Qualquer parser em qualquer linguagem de programação (JavaScript, Python, Go, Rust) lê instantaneamente a chave `"city"` e obtém o valor `"Kyiv"` sem ambiguidades.
```mermaid
flowchart LR
A["Клієнтський UI
(React / Mobile App)"] -->|HTTP POST JSON| B["REST API Сервер
(Node.js / Python)"]
B -->|SQL / NoSQL JSONB| C["База даних
(PostgreSQL / MongoDB)"]
B -->|Structured Output JSON| D["LLM / AI-Агент
(Claude / OpenAI)"]
```
### Por que o JSON não depende do JavaScript
Apesar do nome, o JSON é um formato de texto totalmente independente de linguagem. Ele possui seu próprio padrão RFC (RFC 8259) e é suportado por todos os ecossistemas modernos através do tipo MIME padrão `application/json`.
---
## 2. Anatomia do JSON: sintaxe de objetos, arrays e primitivos
Todos os dados no formato JSON são construídos em torno de dois contêineres principais (objetos e arrays) e seis tipos básicos de valores.
### Objeto (JSON Object)
Um objeto representa um conjunto não ordenado de pares `chave: valor`, obrigatoriamente envolvidos por chaves `{}`. A chave deve ser sempre uma string textual entre aspas duplas.
```json
{
"username": "alex_dev",
"email": "alex@example.com",
"role": "admin"
}
```
### Array (JSON Array)
Um array é uma lista ordenada de valores de qualquer tipo, envolvida por colchetes `[]`. Os elementos do array são indexados a partir de zero.
```json
{
"supportedLocales": ["uk", "en", "es", "de"],
"primeNumbers": [2, 3, 5, 7, 11]
}
```
### Tipos de valores permitidos (Values)
No JSON, são permitidos exatamente 6 tipos de valores:
| Tipo de Valor | Descrição e regras de escrita | Exemplo |
| :--- | :--- | :--- |
| **String** | Sequência de caracteres Unicode entre aspas duplas | `"Hello, World!"` |
| **Number** | Inteiro ou decimal (sem aspas, sem hexadecimal) | `42`, `-12.5`, `1.5e3` |
| **Boolean** | Apenas minúsculas: `true` ou `false` | `true`, `false` |
| **Null** | Indicação de ausência consciente de valor | `null` |
| **Object** | Contêiner aninhado de pares chave-valor | `{"nested": true}` |
| **Array** | Lista aninhada de elementos | `[1, 2, 3]` |
---
## 3. Regras rígidas de sintaxe e armadilhas comuns
A sintaxe do JSON é muito mais rigorosa do que a flexibilidade encontrada em JavaScript ou Python. Um erro em um único caractere quebra a validação de todo o documento.
### As cinco principais regras de sintaxe
1. **Apenas aspas duplas:** Chaves e strings devem estar entre `"aspas duplas"`. Aspas simples `'text'` causam um erro fatal no parser.
2. **Nenhuma vírgula final (Trailing Commas):** É estritamente proibido colocar uma vírgula após o último elemento de um objeto ou array.
3. **Dois-pontos como único separador:** A chave é separada do valor exclusivamente por dois-pontos `:`.
4. **Ausência total de comentários:** A especificação JSON não suporta comentários `//` ou `/* */`. Qualquer explicação deve ser formatada como campos normais do documento (por exemplo, `"_comment": "Explicação"`).
5. **Tipos de dados proibidos:** Não é possível enviar `undefined`, `NaN`, `Infinity`, expressões regulares ou funções via JSON.
### Comparação entre JSON válido e inválido
:::tabs
@tab Exemplo Válido
```json
{
"product": "MacBook Pro",
"price": 1999.99,
"inStock": true,
"tags": ["laptop", "apple", "m-series"]
}
```
@tab Exemplo Inválido (Erros Comuns)
```json
{
product: 'MacBook Pro', // Помилка: одинарні лапки та ключ без лапок
"price": 1999.99,
"inStock": true,
"tags": ["laptop", "apple",], // Помилка: висяча кома
} // Помилка: висяча кома перед закриваючою дужкою
```
:::
---
## 4. Diferenças entre JSON e Objetos JavaScript
Iniciantes frequentemente confundem literais de objeto JavaScript com o formato JSON. No entanto, há uma diferença fundamental entre eles.
```mermaid
flowchart TD
subgraph Текстовий_Рядок["JSON (Символьний потік)"]
J["'{\"name\":\"Max\",\"age\":30}'"]
end
subgraph Пам'ять_Програми["JavaScript Object (Структура в RAM)"]
O["{ name: 'Max', age: 30 }"]
end
J -->|JSON.parse| O
O -->|JSON.stringify| J
```
### Tabela de diferenças fundamentais
| Característica | Objeto JavaScript | JSON (Formato de Texto) |
| :--- | :--- | :--- |
| **Forma de existência** | Estrutura de dados viva na memória RAM | String de texto (sequência de bytes) |
| **Requisitos de chaves** | Podem ser sem aspas ou Symbol | Obrigatoriamente strings entre aspas duplas |
| **Tipos suportados** | Funções, métodos, `Date`, `Map`, `Set`, `undefined` | Apenas 6 tipos básicos (string, number, bool, null, obj, arr) |
| **Comentários** | Permitidos `//` e `/* */` | Totalmente proibidos |
| **Vírgulas finais** | Permitidas pelos padrões JS modernos | Rigorosamente proibidas pelo padrão |
---
## 5. Navegação e leitura de estruturas de dados aninhadas
Em projetos reais, as respostas da API contêm hierarquias profundas. Para acessar um valor específico, utiliza-se a notação de ponto (`.`) para objetos e índices (`[]`) para arrays.
### Exemplo de documento complexo
```json
{
"orderId": "ORD-94821",
"customer": {
"fullName": "Тарас Шевченко",
"contacts": {
"email": "taras@example.org",
"phones": ["+380501112233", "+380679998877"]
}
},
"items": [
{ "id": 1, "title": "Монітор 4K", "price": 450, "qty": 1 },
{ "id": 2, "title": "Механічна клавіатура", "price": 120, "qty": 2 }
]
}
```
### Caminhos de acesso aos elementos
- `order.orderId` $\rightarrow$ retorna `"ORD-94821"`
- `order.customer.fullName` $\rightarrow$ retorna `"Taras Shevchenko"`
- `order.customer.contacts.phones[0]` $\rightarrow$ retorna o primeiro número `"+380501112233"`
- `order.items[1].price` $\rightarrow$ retorna o preço do segundo item `120`
> [!TIP]
> No JavaScript moderno, para evitar erros `TypeError: Cannot read properties of undefined`, use sempre encadeamento opcional: `order?.customer?.contacts?.email`.
---
## 6. JSON em REST API: requisições, respostas e cabeçalhos
Praticamente todos os serviços web modernos usam JSON como protocolo de transporte da carga útil (Payload) via HTTP.
```mermaid
sequenceDiagram
autonumber
actor Client as Клієнт (Браузер / Додаток)
participant Server as REST API Сервер
Note over Client: Підготовка об'єкта та серіалізація
Client->>Server: POST /api/users (Header: Content-Type: application/json)
Note over Server: Десеріалізація JSON, валідація, запис у БД
Server-->>Client: 201 Created (Header: Content-Type: application/json)
Note over Client: Читання response.json()
```
### Cabeçalhos HTTP-chave
1. **`Content-Type: application/json`:** Indica ao servidor ou cliente que o corpo da requisição (Request Body) ou da resposta (Response Body) contém uma string JSON válida.
2. **`Accept: application/json`:** O cliente informa ao servidor que espera receber a resposta exclusivamente no formato JSON (e não XML ou HTML).
---
## 7. Serialização e desserialização: parse e stringify
A conversão de objetos vivos da memória para texto é chamada de **serialização** (*Serialization*), enquanto a conversão inversa de texto para objeto é a **desserialização** (*Deserialization*).
:::tabs
@tab JavaScript / TypeScript
```typescript
// 1. Десеріалізація (Текст -> Об'єкт)
const jsonString = '{"title":"Ноутбук","price":1200}';
const product = JSON.parse(jsonString);
console.log(product.title); // "Ноутбук"
// 2. Серіалізація (Об'єкт -> Текст)
const user = { name: "Данило", active: true };
const serialized = JSON.stringify(user, null, 2); // форматування з відступом у 2 пробіли
```
@tab Python
```python
import json
# 1. Десеріалізація
raw_text = '{"title": "Ноутбук", "price": 1200}'
product = json.loads(raw_text)
print(product["title"])
# 2. Серіалізація
user_dict = {"name": "Данило", "active": True}
json_string = json.dumps(user_dict, indent=2, ensure_ascii=False)
```
@tab Go
```go
package main
import (
"encoding/json"
"fmt"
)
type Product struct {
Title string `json:"title"`
Price int `json:"price"`
}
func main() {
raw := []byte(`{"title":"Ноутбук","price":1200}`)
var p Product
json.Unmarshal(raw, &p)
fmt.Println(p.Title)
}
```
:::\n
---
## 8. Diagnóstico de erros de sintaxe e validação
Se o texto contiver qualquer erro sintático, a chamada `JSON.parse()` lança uma exceção `SyntaxError`, que pode interromper abruptamente a aplicação.
```javascript
try {
const data = JSON.parse(untrustedUserInput);
} catch (error) {
console.error("Невалідний JSON:", error.message);
}
```
### Checklist de diagnóstico rápido
- [ ] Todas as chaves `{}` e colchetes `[]` estão fechados?
- [ ] Todas as chaves estão entre aspas duplas `""`?
- [ ] Não há vírgula final antes do último fechamento?
- [ ] Valores como `undefined`, `NaN` ou comentários não entraram no texto?
- [ ] As aspas internas nas strings estão escapadas: `"quote": "Palavra \"entre aspas\""`?
---
## 9. JSON Schema: verificação de contratos e estrutura
Um JSON sintaticamente correto não garante que os dados tenham a estrutura de negócio correta. Se a API espera um número `age` e recebe a string `"vinte"`, o programa falhará na etapa de cálculo.
Para descrever formalmente os requisitos de estrutura, usa-se o padrão **JSON Schema**.
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "UserRegistrationSchema",
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"age": {
"type": "integer",
"minimum": 18
},
"roles": {
"type": "array",
"items": { "type": "string" },
"minItems": 1
}
},
"required": ["email", "age"]
}
```
Qualquer validador (como Ajv em JavaScript ou jsonschema em Python) verificará automaticamente os dados de entrada contra este contrato antes de enviá-los à base de dados.
---
## 10. Dados estruturados para LLMs, chamadas de função e agentes de IA
No desenvolvimento moderno com inteligência artificial, respostas textuais em formato livre estão gradualmente dando lugar a **Structured Outputs**.
Agentes de IA (como Claude Code, OpenAI Function Calling, LangChain) usam JSON para chamar ferramentas externas:
```json
{
"name": "sendEmailNotification",
"arguments": {
"recipient": "user@example.com",
"subject": "Рахунок сформовано",
"invoiceId": "INV-2026-09"
}
}
```
### Como garantir o retorno de JSON puro de um modelo de linguagem
1. **Especifique o schema no prompt do sistema:** Envie sempre o modelo TypeScript exato ou o JSON Schema.
2. **Exija saída bruta:** Use a instrução: *"Return ONLY a valid raw JSON object. Do not wrap in markdown code blocks or add introductory text."*
3. **Use o modo Structured Outputs:** Nos provedores de API (Anthropic Tool Use / OpenAI JSON Mode), ative o schema de validação forçada no nível do gerador de tokens.
---
## 11. Comparação de formatos: JSON, YAML, XML e TOML
| Formato | Legibilidade humana | Suporte a comentários | Volume de marcação | Principal área de uso |
| :--- | :--- | :--- | :--- | :--- |
| **JSON** | Média / Alta | Não | Mínimo | Web API, comunicação cliente-servidor, chamadas de IA |
| **YAML** | Muito alta | Sim | Zero (indentação) | Configurações CI/CD (GitHub Actions, K8s) |
| **TOML** | Muito alta | Sim | Baixo | Configurações de projeto (Cargo, pyproject.toml) |
| **XML** | Baixa | Sim | Alto (tags) | Sistemas enterprise legados, SOAP, SVG |
---
## 12. Workshop prático, autoavaliação e checklist final
Vamos consolidar todas as habilidades adquiridas em um ciclo completo: desde a obtenção de dados da API até a validação e leitura.
### Cenário completo de obtenção e leitura de dados
```typescript
// Отримання даних користувача через Fetch API
async function fetchUserProfile(userId: number) {
try {
const response = await fetch(`https://api.example.com/users/${userId}`, {
headers: { Accept: "application/json" }
});
if (!response.ok) {
throw new Error(`HTTP Error: ${response.status}`);
}
// Автоматична десеріалізація JSON
const user = await response.json();
// Безпечне читання значень
console.log(`Користувач: ${user.name}`);
console.log(`Основна навичка: ${user.skills?.[0] ?? 'відсутня'}`);
return user;
} catch (err) {
console.error("Помилка отримання профілю:", err);
}
}
```
### Autoavaliação rápida
> **1. Qual erro ocorrerá se usarmos aspas simples para uma string em um arquivo JSON?**
>
> > [!TIP]
> > **Resposta:** Ocorrerá um erro de parsing `SyntaxError: Unexpected token ' in JSON`. A especificação JSON permite exclusivamente aspas duplas `""`.
> **2. Por que não podemos colocar uma vírgula após o último elemento em um objeto JSON?**
>
> > [!TIP]
> > **Resposta:** O padrão JSON proíbe vírgulas finais (trailing commas). O parser espera, após a vírgula, o próximo par chave-valor; se encontrar o fechamento `}`, ocorre um erro fatal de sintaxe.
> **3. Para que serve o padrão JSON Schema?**
>
> > [!TIP]
> > **Resposta:** Para verificar a estrutura de negócio e os tipos de dados no documento (presença de campos obrigatórios, valores mínimos numéricos, formato de email), e não apenas a validade básica da sintaxe.
### Checklist final de trabalho com JSON
- [ ] Todas as strings e chaves estão formatadas com aspas duplas `""`.
- [ ] Verificada a ausência de vírgulas finais antes de `}` e `]`.
- [ ] Todos os comentários foram removidos do documento.