Primeiros passos
Estrutura básica
O JSON suporta 6 tipos de dados: string, number, boolean, null, array e object. As chaves devem ser strings entre aspas duplas. O JSON é independente de linguagem e fácil de ler para humanos e máquinas.
{
"name": "Alice",
"age": 30,
"isStudent": false,
"height": 1.65,
"nullValue": null,
"hobbies": ["reading", "coding", "music"],
"address": {
"city": "NYC",
"zip": "10001"
}
}Regras de sintaxe do JSON
O JSON tem sintaxe estrita: chaves e strings usam apenas aspas duplas, vírgulas separam elementos, e vírgulas finais são proibidas. O documento inteiro deve ser um único valor JSON. O JSON padrão não tem comentários — use um pré-processador ou JSON5 se precisar deles.
{
"key": "value", // key MUST be a double-quoted string
"nested": { "a": 1 }, // objects use { } with comma-separated pairs
"list": [1, 2, 3] // arrays use [ ] with comma-separated values
}
// Rules:
// - Double quotes only for strings and keys (no single quotes)
// - Comma separates members; NO trailing comma
// - The whole document is ONE value (usually an object or array)
// - No comments allowed in standard JSONComentários no JSON
O JSON padrão proíbe comentários. Alternativas comuns: adicione um campo '_comment' (ignorado pelo código), use JSONC/JSON5 (suportados pelo VS Code e muitas ferramentas), ou remova os comentários antes de interpretar com uma biblioteca como comment-json ou JSON.minify.
// Standard JSON does NOT allow comments.
// Workaround 1: include a descriptive field
{
"_comment": "This is a config file for the app",
"port": 8080
}
// Workaround 2: use JSON5 or JSONC (VS Code settings)
{
// line comment
"port": 8080 /* block comment */
}
// Workaround 3: strip comments before parsing
// (e.g., JSON.minify, comment-json npm package)Espaços em branco e formatação
Espaços em branco fora das strings são insignificantes — as formas compacta e formatada interpretam para o mesmo valor. JSON compacto economiza banda; a forma formatada (indentação de 2 espaços é comum) ajuda na legibilidade e nos diffs. A maioria dos serializadores oferece uma opção 'pretty'.
// These are all equivalent:
{"a":1,"b":2} // compact (no whitespace)
{ "a": 1, "b": 2 } // readable
{
"a": 1,
"b": 2
} // pretty-printed
// Whitespace between tokens is insignificant.
// Use compact for transmission, pretty for humans.Extensão de arquivo e MIME type
A extensão de arquivo padrão é .json e o MIME type é application/json. Variantes como JSONC, JSON5, GeoJSON e NDJSON têm convenções próprias. Sempre use codificação UTF-8; o BOM é desencorajado.
// File extensions:
// .json standard JSON
// .jsonc JSON with comments (VS Code, TypeScript config)
// .json5 JSON5 (relaxed syntax)
// .geojson GeoJSON (geographic data)
// .ndjson Newline-Delimited JSON (JSON Lines)
// .har HTTP Archive (JSON-based)
// MIME type:
Content-Type: application/json
// Older/alternate MIME types (avoid):
// text/json (non-standard)
// application/x-json (non-standard)
// UTF-8 is the default and recommended encoding.Categorias de valores JSON
Os valores JSON se dividem em seis tipos: string, number, boolean, null, array, object. Arrays e objetos são estruturados (podem conter outros valores); o resto são primitivos. Um documento JSON válido é um valor — comumente um objeto ou array, mas um número ou string solto também é válido.
// A JSON value is exactly one of these six types:
"hello" // string
42 // number
3.14 // number
true // boolean
false // boolean
null // null
[1, 2, 3] // array
{ "a": 1 } // object
// Structured types: array, object
// Primitive types: string, number, boolean, null
// A standalone JSON document is a single value of any type.Tipos de dados
Tipo string
Strings JSON são texto Unicode entre aspas duplas. Escapes comuns: \" (aspas), \\ (barra invertida), \/ (barra), \n, \t, \r, \b, \f, e \uXXXX para qualquer code point Unicode. Aspas simples não são permitidas como delimitadores de string.
{
"single": "double quotes only",
"empty": "",
"escaped": "He said \"hi\" and C:\\Users",
"unicode": "Cafu00e9 \u00e9 \u1F600",
"multiline": "line1\nline2\ttabbed"
}
// Strings MUST use double quotes.
// Single quotes are NOT valid in JSON.Tipo number
Números JSON seguem um subconjunto do double IEEE 754: inteiros, decimais e notação científica (por exemplo, 6.022e23). Zeros à esquerda são proibidos (007 é inválido). NaN, Infinity e -Infinity NÃO são válidos — codifique-os como null ou strings se necessário.
{
"integer": 42,
"negative": -7,
"float": 3.14,
"zero": 0,
"scientific": 6.022e23,
"small": 1.5e-10
}
// Numbers are NOT quoted.
// No leading zeros (007 is invalid).
// No NaN, Infinity, or -Infinity (not valid JSON).Tipo boolean
Booleanos JSON são as palavras-chave literais true e false (minúsculas, sem aspas). 'true'/'false' entre aspas são strings. O JSON não tem conceito de 0/1 ou yes/no como booleanos — converta-os no código da sua aplicação.
{
"enabled": true,
"disabled": false,
"flag": true
}
// Booleans are the bare keywords true and false.
// They are NOT quoted ("true" is a string).
// 0/1, yes/no, on/off are NOT booleans in JSON.Tipo null
O null do JSON é a palavra-chave solta null (sem aspas). Sinaliza a ausência intencional de um valor. Note que null é distinto de uma string vazia '', de 0, de false ou de uma chave ausente. Muitas linguagens mapeiam null para None/nil/null.
{
"middleName": null,
"deletedAt": null,
"optional": null
}
// null is a bare keyword (unquoted).
// "null" (quoted) is a string, not null.
// null represents the intentional absence of value.Tipo array
Arrays JSON são listas ordenadas envoltas em [ ], separadas por vírgulas, com índice a partir de zero. Podem conter qualquer valor JSON, incluindo tipos mistos e arrays/objetos aninhados. Arrays vazios [] são válidos. A ordem é preservada e significativa.
{
"numbers": [1, 2, 3],
"mixed": [1, "two", true, null],
"nested": [[1, 2], [3, 4]],
"objects": [
{ "id": 1 },
{ "id": 2 }
],
"empty": []
}
// Arrays are ordered, zero-indexed, and can hold mixed types.Tipo object
Objetos JSON são coleções não ordenadas de chave/valor envoltas em { }. As chaves devem ser strings únicas entre aspas duplas; os valores podem ser de qualquer tipo JSON. Embora objetos sejam conceitualmente não ordenados, a maioria dos parsers preserva a ordem de inserção; não dependa da ordem para correção.
{
"user": {
"id": 1,
"name": "Alice",
"roles": ["admin", "user"],
"active": true
},
"empty": {}
}
// Objects are unordered collections of key/value pairs.
// Keys MUST be unique strings (double-quoted).
// Values can be any JSON type.Strings
Básico de strings
Strings JSON são sequências de caracteres Unicode entre aspas duplas. A barra pode ser escapada (\/) mas não precisa — útil ao embutir JSON em tags <script>. Strings vazias são válidas.
{
"name": "Alice",
"email": "[email protected]",
"url": "https://example.com/path?q=1",
"path": "C:\\Users\\alice",
"empty": ""
}
// Strings are double-quoted Unicode text.
// Forward slash may be escaped as \/ but does not have to be.Sequências de escape
O JSON suporta estes escapes: \" (aspas), \\ (barra invertida), \/ (barra), \b (backspace), \f (form feed), \n (quebra de linha), \r (retorno de carro), \t (tabulação) e \uXXXX (code point Unicode). Qualquer outra sequência com barra invertida é inválida.
{
"quote": "She said \"hello\"",
"backslash": "C:\\Users\\name",
"newline": "line1\nline2",
"tab": "col1\tcol2",
"carriage": "a\rb",
"backspace": "a\bb",
"formfeed": "a\fb",
"slash": "a\/b"
}
// Valid escapes: \" \\ \/ \b \f \n \r \t \uXXXXCaracteres Unicode
Use \uXXXX para qualquer code point Unicode. Caracteres acima de U+FFFF (como muitos emojis) exigem um surrogate pair: dois escapes \u. Parsers modernos também aceitam o caractere UTF-8 bruto diretamente na string — \uXXXX serve principalmente por segurança ou quando você não pode digitar o caractere.
{
"eacute": "Caf\u00e9",
"euro": "Price: \u20ac10",
"emoji": "Smile \ud83d\ude00",
"chinese": "\u4f60\u597d",
"raw": "Cafu00e9 u00e9 \u00e9"
}
// \uXXXX encodes a code point in the Basic Multilingual Plane.
// Surrogate pairs (two \u escapes) encode characters above U+FFFF.
// Modern parsers also accept the raw UTF-8 character directly.Caracteres especiais em strings
Dentro de strings JSON, a aspa dupla e a barra invertida devem sempre ser escapadas (\" e \\). Outros caracteres especiais (HTML, SQL, regex) seguem suas próprias regras, mas o JSON só exige escapar \" e \\ (mais caracteres de controle). Uma barra invertida literal é escrita como \\.
{
"html": "<div class=\"x\">Hi</div>",
"sql": "SELECT * FROM t WHERE name='O''Brien'",
"regex": "^\\d{3}-\\d{4}$",
"json": "{ \"k\": \"v\" }",
"cmd": "echo \"hello\""
}
// Backslash is the universal escape character.
// To include a literal backslash, write \\.Strings multilinha (alternativa)
Strings JSON não podem conter quebras de linha literais — você precisa escapá-las como \n. Para conteúdo multilinha, embuta \n na string, use um array de strings de linha, ou mude para um formato como YAML ou JSON5 que suporta strings multilinha. Quebras de linha literais sem escape são erro de sintaxe.
// JSON does NOT support real multi-line strings.
// The following is INVALID:
// { "text": "line1
// line2" }
// Workaround 1: escape the newline
{ "text": "line1\nline2" }
// Workaround 2: array of lines
{ "lines": ["line1", "line2"] }
// Workaround 3: JSON5 allows continued strings (still single logical line)Pegadinhas comuns de strings
Erros comuns de string: usar aspas simples, deixar vírgula final, esquecer de escapar aspas duplas internas, e embutir caracteres de controle literais (tab/quebra de linha) em vez de seus escapes \t/\n. Um parser estrito rejeita esses casos.
// WRONG: single quotes
// { 'name': 'Alice' }
// WRONG: trailing comma
// { "a": 1, }
// WRONG: unescaped quote
// { "msg": "He said "hi"" }
// WRONG: literal tab/newline in string
// { "x": "a<TAB>b" }
// RIGHT:
{ "name": "Alice", "msg": "He said \"hi\"" }Números
Integer e float
O JSON tem um único tipo number que cobre inteiros e valores de ponto flutuante. Não há tipo inteiro separado no nível da sintaxe — bindings de linguagem podem mapear inteiros grandes para int, long, float ou decimal, dependendo do valor e da biblioteca.
{
"count": 100,
"negative": -42,
"temperature": -273.15,
"pi": 3.14159,
"zero": 0,
"negativeZero": -0
}
// Integers and floats use the same number type.
// JSON does not distinguish int from float at the syntax level.Notação científica
O JSON suporta notação científica: uma mantissa seguida de e ou E e um expoente opcional com sinal (6.022e23 = 6.022 * 10^23). Tanto e quanto E são aceitos. Essencial para números muito grandes ou muito pequenos em dados científicos.
{
"avogadro": 6.022e23,
"planck": 6.626e-34,
"speedOfLight": 2.998e8,
"small": 1.5E-10
}
// e or E is allowed (case-insensitive).
// 6.022e23 means 6.022 * 10^23.
// The exponent may be negative.Precisão numérica
Números JSON são tipicamente interpretados como doubles IEEE 754, então inteiros acima de 2^53-1 (9007199254740991) perdem precisão em JavaScript. Valores decimais como 0.1 não podem ser representados exatamente. Para dinheiro ou inteiros de precisão arbitrária, codifique-os como strings e use um tipo Decimal/BigInteger no seu código.
{
"big": 9007199254740993,
"decimal": 0.1,
"sum": 0.1,
"money": 19.99
}
// JavaScript stores numbers as IEEE 754 doubles.
// Integers are safe up to 2^53 - 1 (9007199254740991).
// 0.1 + 0.2 === 0.30000000000000004 (float precision loss).
// For money or big integers, parse as string or use a Decimal type.Valores especiais (não permitidos)
O JSON padrão não permite NaN, Infinity ou -Infinity. Alternativas: use null para NaN, codifique Infinity como string, ou use um valor sentinela finito. Alguns serializadores (o json do Python por padrão, JSON5) emitem-nos como extensões, mas a saída não é padrão e pode ser rejeitada por parsers estritos.
// NaN, Infinity, and -Infinity are NOT valid JSON.
// INVALID:
// { "x": NaN }
// { "y": Infinity }
// { "z": -Infinity }
// Common workarounds:
{
"x": null, // represent NaN/null
"y": "Infinity", // encode as a string
"z": 1.7976931348623157e308 // use a finite max
}
// Many serializers (e.g., Python json) accept these as extensions
// but the output is not standard JSON.Formatos de número
Números JSON válidos: menos opcional, parte inteira (sem zeros à esquerda, exceto 0), parte fracionária opcional, expoente opcional. Hex (0x), binário (0b), octal, underscores, + à esquerda, zeros à esquerda e um ponto sem dígitos dos dois lados são inválidos.
// VALID JSON numbers:
42
-7
0
3.14
-0.5
6.022e23
1.5E-10
100.00
// INVALID:
007 // leading zero
.5 // no leading digit
5. // no trailing digit after dot
+5 // leading plus sign
0x1F // hex
0b101 // binary
1_000 // underscoresNúmeros grandes e BigInt
Para valores acima de 2^53-1 (por exemplo, IDs snowflake do Twitter, inteiros de 64 bits, saldos grandes), codifique-os como strings para evitar perda de precisão. Se precisar usar um reviver no JSON.parse para converter números em BigInt, lembre que BigInt não pode ser re-serializado pelo JSON.stringify sem um replacer — strings são mais seguras na rede.
{
"snowflake": "1234567890123456789",
"timestamp": 1696000000000,
"balance": "99999999999999999999"
}
// Numbers above 2^53-1 lose precision in JS.
// Use STRINGS for IDs, snowflakes, and big integers.
// In JavaScript, parse with a reviver:
// JSON.parse(str, (k, v) =>
// typeof v === "number" && v > Number.MAX_SAFE_INTEGER
// ? BigInt(v) : v); // careful: BigInt can't be in JSON.stringify
// Better: keep them as strings on the wire.Booleanos e null
Valores booleanos
Booleanos JSON são as palavras-chave soltas true e false. 'true'/'false' entre aspas são strings. O JSON não tem conceito de truthy/falsy no nível da sintaxe — 1, 0, yes, no, on, off são strings ou números, não booleanos. Converta-os no código da aplicação.
{
"enabled": true,
"disabled": false,
"isPublic": true,
"isActive": false
}
// Only two boolean values: true and false (lowercase, unquoted).
// "true" (quoted) is a STRING, not a boolean.
// 1/0, yes/no, on/off are NOT booleans.Significado de null
O null do JSON sinaliza a ausência intencional de um valor. É distinto de uma chave ausente (chave fora do objeto), de uma string vazia '', de 0, de false ou de uma coleção vazia. Use null quando um campo existe, mas não tem valor; omita a chave quando o campo em si não se aplica.
{
"middleName": null,
"deletedAt": null,
"parent": null,
"optional": null
}
// null means "no value" or "intentionally absent".
// Distinct from:
// - missing key (key not present at all)
// - empty string ""
// - 0 or false
// - empty array [] or object {}Null vs vazio vs ausente
Três estados distintos: uma chave com valor vazio (""), uma chave explicitamente null, e uma chave ausente. Em JavaScript, undefined significa que a chave está ausente, enquanto null significa que ela está presente, mas não tem valor. APIs devem documentar qual convenção usam para campos opcionais.
{
"name": "Alice",
"nickname": "", // empty string (present, empty)
"middleName": null, // explicit null (present, no value)
// "maidenName" // missing (key not in object)
}
// In JavaScript:
// obj.nickname === "" // true
// obj.middleName === null // true
// obj.maidenName === undefined // true (key absent)
// "maidenName" in obj // false
// Choose deliberately: null vs "" vs missing.Usando booleanos em condições
Ao consumir booleanos JSON, prefira comparação estrita (=== true) a checagens truthy se precisar distinguir false de ausente. Em respostas de API, sempre inclua campos booleanos, mesmo quando false — omiti-los força os clientes a adivinhar o padrão.
{
"isAdmin": true,
"canEdit": false,
"active": true
}
// In application code (JavaScript):
// if (user.isAdmin) { ... } // truthy check
// const canEdit = user.canEdit === true; // strict boolean check
// Be careful: a missing 'canEdit' key is undefined (falsy),
// but explicit false is also falsy. Distinguish if needed.
// API design: always send the boolean, even when false.Pegadinhas comuns
Pegadinhas comuns: colocar aspas em true/false/null os transforma em strings; usar True/TRUE/None (Python) ou true/false com caixa errada é inválido; o JSON não tem undefined (apenas null). As únicas formas válidas são as palavras-chave em minúsculas e sem aspas true, false e null.
// Pitfall 1: quoting booleans/null
// { "x": "true" } -> x is a STRING, not a boolean
// { "y": "null" } -> y is a STRING, not null
// Pitfall 2: wrong case
// { "x": True } -> INVALID (Python-style, not JSON)
// { "x": TRUE } -> INVALID
// { "x": None } -> INVALID
// Pitfall 3: confusing null with undefined
// null exists in JSON; undefined does NOT.
// Correct:
{ "x": true, "y": null }Arrays
Básico de arrays
Arrays JSON são listas ordenadas, com índice a partir de zero, envoltas em [ ], com valores separados por vírgulas. Arrays vazios e de elemento único são válidos. A ordem é significativa e preservada pelos parsers. Não se permite vírgula final.
{
"numbers": [1, 2, 3, 4, 5],
"strings": ["a", "b", "c"],
"booleans": [true, false, true],
"empty": [],
"single": [42]
}
// Arrays are ordered, zero-indexed lists in [ ].
// Elements are separated by commas (no trailing comma).
// Empty arrays [] and single-element arrays are valid.Arrays de tipos mistos
Arrays JSON podem legalmente conter tipos mistos ([1, 'two', true, null]). Isso é válido, mas frequentemente indica design de schema fraco. Arrays homogêneos (todas strings, cada item objeto) são mais fáceis de validar, documentar e consumir. Use um schema para impor os tipos dos elementos.
{
"mixed": [1, "two", true, null, 3.14],
"nested": [[1, 2], "x", { "a": 1 }]
}
// JSON arrays CAN hold values of different types.
// This is valid but often a sign of weak schema design.
// Prefer homogeneous arrays for clarity and validation.Arrays aninhados
Arrays podem se aninhar a qualquer profundidade, útil para matrizes, grids e estruturas de árvore. O JSON não impõe que arrays aninhados tenham o mesmo comprimento (um array 'irregular' é válido). Se precisar de uma matriz retangular, imponha isso com um schema ou código de aplicação.
{
"matrix": [
[1, 2, 3],
[4, 5, 6],
[7, 8, 9]
],
"ragged": [[1, 2], [3, 4, 5], [6]]
}
// Arrays can nest arbitrarily deep.
// JSON does not enforce rectangular shape—use a schema if needed.Array de objetos
Um array de objetos é o padrão mais comum para listas de registros (usuários, produtos, postagens). Cada elemento normalmente tem a mesma forma, mas o JSON não impõe isso — use um schema (o 'items' do JSON Schema) para validar que os elementos se conformam.
{
"users": [
{ "id": 1, "name": "Alice" },
{ "id": 2, "name": "Bob" },
{ "id": 3, "name": "Carol" }
],
"empty": []
}
// A very common pattern: a list of records.
// Each element is an object with the same shape.Arrays vazios e de elemento único
Arrays vazios [] e de elemento único são válidos. No design de API, distinga [] (presente, lista vazia) de null (presente, sem lista) e de uma chave ausente (campo não se aplica). Retornar [] para 'nenhum item' costuma ser mais amigável que null.
{
"empty": [],
"single": [42],
"tags": [],
"items": ["one"]
}
// Both forms are valid.
// Distinguish [] from null and from a missing key:
// "tags": [] -> present, empty list
// "tags": null -> present, no list
// // (no tags) -> missing keyAcesso a arrays em código
Após a interpretação, arrays JSON viram arrays/listas nativas na sua linguagem (Array do JS, list do Python, List do Java etc.). Use acesso por índice, length e iteração padrão. Limites e segurança de tipos são sua responsabilidade — o JSON em si não impõe tipos de elemento.
{
"list": ["a", "b", "c"]
}
// JavaScript:
// const arr = JSON.parse(json).list;
// arr[0] // "a"
// arr.length // 3
// arr.includes("b") // true
// arr.map(x => x.toUpperCase()) // ["A", "B", "C"]
// Python:
// data = json.loads(json_str)
// data["list"][0] # "a"
// len(data["list"]) # 3Objetos
Básico de objetos
Objetos JSON são coleções não ordenadas de pares chave/valor envoltas em { }. As chaves devem ser strings entre aspas duplas; os valores podem ser de qualquer tipo JSON. Pares são separados por vírgulas, sem vírgula final. Objetos são a estrutura JSON de nível superior mais comum.
{
"id": 1,
"name": "Alice",
"email": "[email protected]",
"active": true
}
// Objects are unordered { } collections of key/value pairs.
// Keys MUST be double-quoted strings.
// Pairs are comma-separated (no trailing comma).Regras de nomenclatura de chaves
Chaves JSON podem ser qualquer string entre aspas duplas, incluindo vazia, com espaços, pontos ou dígitos. Porém, para clareza de API, prefira camelCase, snake_case ou kebab-case consistentes. Evite espaços, pontos (conflito com sintaxe de path) e chaves vazias em APIs públicas.
{
"simple": "ok",
"with-dash": "ok",
"with_underscore": "ok",
"with.dot": "ok",
"with space": "ok (but avoid)",
"123numeric": "ok (but avoid)",
"": "empty key is valid"
}
// Keys are arbitrary strings (double-quoted).
// Convention: use camelCase, snake_case, or kebab-case consistently.
// Avoid empty keys and keys with spaces/dots in APIs.Objetos aninhados
Objetos podem se aninhar a qualquer profundidade, útil para dados hierárquicos. Aninhamento profundo é válido, mas pode prejudicar a legibilidade e aumentar o acoplamento. Para APIs públicas, prefira uma estrutura mais plana ou use referências (IDs) em vez de árvores profundamente aninhadas.
{
"user": {
"name": "Alice",
"address": {
"street": "123 Main St",
"city": "NYC",
"geo": { "lat": 40.7, "lng": -74.0 }
}
}
}
// Objects can nest arbitrarily deep.
// Deep nesting is valid but can hurt readability—flatten when sensible.Objeto com arrays
Combinar objetos (para campos com chave) e arrays (para listas ordenadas) modela quase qualquer dado do mundo real. Um padrão comum é um objeto envolvendo arrays de objetos aninhados (um usuário com pedidos). Use um schema para documentar e validar a forma esperada.
{
"user": {
"name": "Alice",
"roles": ["admin", "user"],
"orders": [
{ "id": 1, "total": 19.99 },
{ "id": 2, "total": 5.99 }
]
}
}
// Combining objects and arrays models most real-world data.Ordem dos membros
A spec do JSON trata objetos como não ordenados. Na prática, a maioria dos parsers modernos (V8 do JavaScript, Python 3.7+, LinkedHashMap do Java) preserva a ordem de inserção, mas você não deve depender disso para correção. Se a ordem importa para hashing ou assinatura, ordene as chaves explicitamente.
{
"z": 1,
"a": 2,
"m": 3
}
// JSON objects are SPECIFIED as unordered.
// In practice, most parsers (JS, Python 3.7+) preserve insertion order.
// DO NOT rely on order for correctness—sort keys if order matters.
// Sorting keys (e.g., for stable hashing):
// JSON.stringify(obj, Object.keys(obj).sort())Chaves duplicadas
A spec do JSON não proíbe chaves duplicadas, mas seu comportamento é indefinido — a maioria dos parsers mantém o último valor, alguns mantêm o primeiro. Chaves duplicadas são fonte comum de bugs sutis. JSON Schema pode impor uniqueKeys; linters e parsers estritos podem rejeitá-las.
// Technically valid JSON, but behavior is UNDEFINED:
{
"name": "Alice",
"name": "Bob"
}
// Most parsers keep the LAST value ("Bob"),
// but some keep the first. Avoid duplicate keys!
// JSON Schema (draft 2019-09+) has 'uniqueKeys' to forbid them.
// JSON.parse in JS keeps the last value (object property override).Estruturas aninhadas
Aninhamento profundo
O JSON permite profundidade de aninhamento arbitrária, mas estruturas muito profundas prejudicam a legibilidade e podem atingir limites de parser (muitos impõem um teto de profundidade, por exemplo, 1000, para prevenir negação de serviço). Prefira estruturas mais planas com IDs/referências para dados profundamente hierárquicos.
{
"a": {
"b": {
"c": {
"d": {
"e": { "value": 42 }
}
}
}
}
}
// Nesting depth is theoretically unlimited.
// Many parsers impose a limit (e.g., 1000) to prevent DoS.
// Deep nesting hurts readability—consider flattening or references.Exemplo do mundo real
JSON do mundo real mistura objetos e arrays para modelar entidades e seus relacionamentos. Este exemplo de pedido aninha customer, items (um array de objetos) e shipping. Use um schema para documentar a forma; mantenha o aninhamento moderado por legibilidade.
{
"order": {
"id": "ord-123",
"customer": {
"id": "cus-1",
"name": "Alice",
"email": "[email protected]"
},
"items": [
{ "sku": "A1", "qty": 2, "price": 9.99 },
{ "sku": "B2", "qty": 1, "price": 19.99 }
],
"shipping": {
"address": { "city": "NYC", "zip": "10001" },
"method": "express"
},
"total": 39.97
}
}Estruturas de árvore
Árvores são modeladas recursivamente: cada nó tem um valor e um array de nós filhos. Esse padrão aparece em sistemas de arquivos, organogramas e ASTs. Fique atento a ciclos — o JSON não tem sintaxe de referência, então grafos cíclicos precisam usar IDs ou ser serializados como lista plana com ponteiros de pai.
{
"name": "root",
"children": [
{
"name": "child-a",
"children": [
{ "name": "grandchild-1", "children": [] },
{ "name": "grandchild-2", "children": [] }
]
},
{ "name": "child-b", "children": [] }
]
}
// Recursive structures: a node contains an array of child nodes.Acessando valores aninhados
Acessar valores profundamente aninhados arrisca TypeError/KeyError se chaves intermediárias estiverem ausentes. Use optional chaining (?. e ?? no JS) ou .get() encadeado (Python) com defaults. Bibliotecas como lodash.get ou jq simplificam a extração profunda e fornecem defaults.
{
"user": { "address": { "city": "NYC" } }
}
// JavaScript (optional chaining):
// const city = data?.user?.address?.city ?? "unknown";
// Python:
// city = data.get("user", {}).get("address", {}).get("city", "unknown")
// Deep access without guards throws on missing keys.
// Use optional chaining or a helper like lodash.get.Achatar dados aninhados
Achatar objetos aninhados (por exemplo, 'user.name' em vez de { user: { name } }) simplifica o acesso para variáveis de ambiente, campos de formulário e indexação de busca. O trade-off é perder estrutura e dificultar a ida e volta. Use uma biblioteca (flat, lodash) para achatar/desachatar.
// Nested form:
{ "user": { "name": "Alice", "city": "NYC" } }
// Flattened form (dot notation):
{ "user.name": "Alice", "user.city": "NYC" }
// Flattened form (separate keys):
{ "userName": "Alice", "userCity": "NYC" }
// Use cases: environment variables, form fields, search indexing.
// Trade-off: simpler access vs. loss of structure.JSON Schema
Básico de schema
JSON Schema é um vocabulário JSON para descrever e validar documentos JSON. A raiz declara $schema (versão do draft) e type. Properties lista campos com seus tipos; required lista chaves obrigatórias. Validadores como Ajv (JS) ou jsonschema (Python) verificam a conformância.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/user.json",
"title": "User",
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "integer", "minimum": 0 }
},
"required": ["name"]
}Validação de tipo
A palavra-chave 'type' valida o tipo JSON de um valor: string, number, integer, boolean, null, array ou object. Pode ser um tipo único ou um array (por exemplo, ['string', 'null'] para uma string opcional anulável). 'integer' casa com números sem parte fracionária.
{
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "integer" },
"active": { "type": "boolean" },
"score": { "type": "number" },
"tags": { "type": "array", "items": { "type": "string" } },
"meta": { "type": "object" },
"middle": { "type": ["string", "null"] }
}
}
// 'type' can be a single type or an array of allowed types.Restrições de string
Restrições de string: minLength, maxLength, pattern (regex), enum (valores permitidos) e format (dica semântica como 'email', 'uri', 'date-time', 'ipv4'). 'format' é apenas anotação por padrão — validadores precisam aderir para impô-la. Use pattern para validação estrita por regex.
{
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 254
},
"username": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]{3,20}$",
"minLength": 3,
"maxLength": 20
},
"bio": { "type": "string", "maxLength": 500 }
}
}
// 'format' is a semantic hint (email, uri, date, ipv4).
// 'pattern' is a regular expression.Restrições numéricas
Restrições numéricas: minimum, maximum (inclusivos), exclusiveMinimum, exclusiveMaximum e multipleOf. Para o tipo 'integer', os valores não podem ter parte fracionária. Combine restrições para modelar faixas (por exemplo, uma nota de 1 a 5).
{
"type": "object",
"properties": {
"age": { "type": "integer", "minimum": 0, "maximum": 150 },
"price": { "type": "number", "minimum": 0, "exclusiveMinimum": 0 },
"rating":{ "type": "integer", "minimum": 1, "maximum": 5 },
"count": { "type": "integer", "multipleOf": 5 }
}
}
// minimum/maximum are inclusive;
// exclusiveMinimum/exclusiveMaximum are exclusive.Restrições de objeto e array
Restrições de array: items (schema do elemento), minItems, maxItems, uniqueItems. Restrições de objeto: required (chaves obrigatórias), properties (schemas dos campos), additionalProperties (false para proibir chaves extras, ou um schema para elas), minProperties, maxProperties.
{
"type": "object",
"properties": {
"id": { "type": "integer" },
"tags": {
"type": "array",
"items": { "type": "string" },
"minItems": 1,
"maxItems": 10,
"uniqueItems": true
}
},
"required": ["id"],
"additionalProperties": false
}
// minItems/maxItems/uniqueItems constrain arrays.
// required lists mandatory keys; additionalProperties
// controls whether extra keys are allowed.Validação avançada
JSON Schema avançado: oneOf/anyOf/allOf combinam subschemas; $ref referencia definições reutilizáveis; if/then/else aplica validação condicional; const exige um valor exato; enum lista os valores permitidos. Esses permitem expressar restrições ricas e tipos reutilizáveis.
{
"oneOf": [
{ "type": "string" },
{ "type": "integer" }
],
"definitions": {
"address": {
"type": "object",
"properties": { "city": { "type": "string" } }
}
},
"properties": {
"home": { "$ref": "#/definitions/address" },
"work": { "$ref": "#/definitions/address" }
},
"if": { "properties": { "type": { "const": "vip" } } },
"then": { "required": ["discount"] }
}
// oneOf/anyOf/allOf combine schemas.
// $ref reuses definitions; if/then/else is conditional.JSONPath
Sintaxe JSONPath
JSONPath é uma linguagem de consulta para JSON, inspirada no XPath. '$' é a raiz, '.' seleciona um filho, '[index]' seleciona um elemento de array, '*' é um curinga, e '..' é descida recursiva. Bibliotecas como jsonpath-plus (JS) ou jsonpath-ng (Python) a implementam.
// JSONPath queries JSON like XPath queries XML.
// Sample data:
{
"store": {
"book": [
{ "category": "fiction", "price": 12.99 },
{ "category": "web", "price": 29.99 }
]
}
}
// Common JSONPath expressions:
$.store.book[0].category // "fiction"
$.store.book[*].price // [12.99, 29.99]
$..price // all prices anywhere
$.store..category // all categories under storeRaiz e filho
'$' referencia a raiz. '.' seleciona um filho pelo nome; '[]' é a alternativa de colchetes que trata chaves com pontos, espaços ou aspas. '[index]' seleciona um elemento de array (base 0); algumas implementações suportam índices negativos para contar do fim.
// '$' = root object/array
// '.' or '[]' = child
$.user.name // dot notation
$['user']['name'] // bracket notation (use for special chars)
$.users[0] // first element of users array
$.users[-1] // last element (some implementations)
// Use bracket notation when keys contain dots, spaces, or quotes:
$['user.name']
$['first name']Descida recursiva
'..' (descida recursiva) casa uma chave ou elemento em qualquer profundidade. '$..price' retorna cada valor 'price', não importa onde apareça. '$..*' retorna cada nó. Inestimável para buscar em JSON grande ou profundamente aninhado quando você não conhece o caminho exato.
{
"a": { "b": { "c": 1 }, "c": 2 }
}
// '..' searches at all depths:
$..c // [1, 2] (all 'c' keys anywhere)
$..a // all 'a' keys
$..* // every node (everything)
// Useful for finding a key without knowing the exact path:
$..price // every price, no matter how nestedExpressões de filtro
Filtros usam [?(expression)], em que '@' refere-se ao item atual. Os operadores suportados variam por implementação, mas tipicamente incluem ==, !=, <, <=, >, >=, && (e), || (ou), e às vezes =~ para regex. Funções como length() e contains() adicionam poder.
// Filter with [?(expression)]:
$.store.book[?(@.price < 20)] // books under 20
$.store.book[?(@.category == 'web')] // web books
$.store.book[?(@.price < 30 && @.category == 'web')]
// '@' refers to the current item being filtered.
// Operators: == != < <= > >= && || =~ (regex in some impls)
// Functions: length(), contains(), matches()Curingas
'*' é um curinga que casa os filhos de um objeto ou os elementos de um array. '$.users[*].name' retorna o 'name' de cada usuário. '$..*' retorna cada nó. Os resultados são retornados como um array de correspondências, mesmo que haja só uma.
{
"users": [
{ "name": "Alice", "age": 30 },
{ "name": "Bob", "age": 25 }
]
}
// '*' matches all elements/children:
$.users[*] // all user objects
$.users[*].name // ["Alice", "Bob"]
$.users[0].* // all values of first user: ["Alice", 30]
$..* // every node in the document
// Wildcards return arrays of matches.Funções e exemplos comuns
Funções JSONPath variam por implementação: length(), min(), max(), avg(), sum(), contains() e matches() são comuns. Combine filtros e descida recursiva para consultas poderosas. Para trabalho em CLI, jq é o padrão de fato e usa uma sintaxe um pouco diferente.
// length(): array length or string length
$.users.length() // number of users
$.store.book[?(@.title.length() > 10)]
// min(), max(), avg(), sum() (some implementations)
$.store.book..price.min()
// Realistic query: titles of cheap web books
$.store.book[?(@.price < 20 && @.category == 'web')].title
// Tools: jq (CLI), jsonpath-plus (JS), jsonpath-ng (Python),
// Jayway (Java), GoJSONQ (Go)JSON vs XML e YAML
Sintaxe JSON vs XML
JSON é mais leve (sem tags de fechamento, tipos nativos para números/booleanos/null) e mapeia diretamente para as estruturas de dados da maioria das linguagens. XML é mais pesado, mas mais rico: atributos, namespaces, conteúdo misto, schemas (XSD) e transforms (XSLT). JSON domina as APIs web; XML persiste em enterprise/SOAP.
// JSON:
{
"name": "Alice",
"age": 30,
"hobbies": ["reading", "coding"]
}
<!-- XML: -->
<person>
<name>Alice</name>
<age>30</age>
<hobbies>
<hobby>reading</hobby>
<hobby>coding</hobby>
</hobbies>
</person>
// JSON: lighter, no closing tags, types (number/boolean/null).
// XML: heavier, supports attributes, namespaces, mixed content.Sintaxe JSON vs YAML
YAML usa indentação em vez de chaves/aspas, suporta comentários, strings multilinha e âncoras/aliases. JSON é mais estrito (aspas obrigatórias, sem comentários), mas mais rápido e mais onipresente. YAML é um superconjunto do JSON — cada arquivo JSON válido também é YAML válido.
# YAML:
name: Alice
age: 30
hobbies:
- reading
- coding
// JSON (equivalent):
{
"name": "Alice",
"age": 30,
"hobbies": ["reading", "coding"]
}
// YAML: no quotes/braces, indentation-based, supports comments.
// JSON: stricter, faster to parse, ubiquitous in APIs.Conversão JSON para YAML
Converter JSON para YAML é direto, porque YAML é um superconjunto do JSON. O yaml.dump do Python e o js-yaml do Node resolvem. O resultado usa indentação e sem aspas (na maior parte). Os comentários e strings multilinha do YAML não fazem a volta a partir do JSON (o JSON não os tem).
// JSON input:
{ "name": "Alice", "roles": ["admin", "user"] }
// YAML output:
name: Alice
roles:
- admin
- user
// Python:
// import yaml, json
// yaml.dump(json.loads(json_str), sort_keys=False)
// Node.js:
// const yaml = require('js-yaml');
// yaml.dump(JSON.parse(jsonStr));Conversão YAML para JSON
Converter YAML para JSON funciona para YAML simples, mas perde recursos específicos do YAML: comentários, âncoras/aliases, streams de múltiplos documentos, tags e chaves complexas. Use yaml.safe_load para evitar execução arbitrária de código a partir de tags personalizadas. O resultado é JSON padrão.
# YAML input:
server:
host: localhost
port: 8080
debug: true
// JSON output:
{
"server": {
"host": "localhost",
"port": 8080,
"debug": true
}
}
// Python:
// import yaml, json
// json.dumps(yaml.safe_load(yaml_str), indent=2)
// Watch for YAML-specific features: anchors, tags, multi-docs.Diferenças de modelagem de dados
JSON modela dados como objetos e arrays — sem atributos nem namespaces. XML adiciona atributos, namespaces, conteúdo misto e schemas ricos. YAML adiciona comentários, âncoras e suporte a múltiplos documentos. TOML mira arquivos de configuração com tabelas. Escolha conforme a necessidade: APIs (JSON), documentos (XML), configuração (YAML/TOML).
// JSON: objects and arrays, no attributes.
// Attribute-style metadata needs a convention (e.g., @_prefix).
// XML: elements + attributes, namespaces, mixed content.
// <book id="b1" category="web"><title>...</title></book>
// YAML: maps, sequences, scalars, anchors, multi-doc.
// Supports comments and multi-line strings natively.
// TOML: tables + key/value, designed for config files.
// Best for configuration; not ideal for nested data.Quando usar cada formato
JSON para APIs web e armazenamento NoSQL (universal, rápido). XML para serviços enterprise, dados centrados em documento (SVG, XHTML) e schemas ricos. YAML para configuração escrita por humanos (CI/CD, docker-compose), graças aos comentários e à legibilidade. TOML para arquivos de configuração pequenos. Casar o formato com o caso de uso.
// Use JSON when:
// - building web/REST APIs (universal browser support)
// - storing structured data (NoSQL databases)
// - configuration with simple needs (package.json)
// Use XML when:
// - enterprise/SOAP web services
// - documents with mixed content (SVG, XHTML, DocBook)
// - you need schemas, namespaces, or XSLT transforms
// Use YAML when:
// - human-written config (CI/CD, docker-compose)
// - you need comments and multi-line strings
// Use TOML when:
// - small config files (Cargo, pyproject)Interpretação em JavaScript
JSON.parse
JSON.parse converte uma string JSON num valor JavaScript. Aceita qualquer valor JSON válido (objeto, array, string, número, booleano, null). JSON inválido lança SyntaxError. Sempre envolva JSON.parse em try/catch ao tratar entrada não confiável.
// Parse a JSON string into a JavaScript value.
const json = '{"name":"Alice","age":30}';
const obj = JSON.parse(json);
console.log(obj.name); // "Alice"
console.log(obj.age); // 30
// JSON.parse accepts a string only.
// Passing a number/boolean/object throws or coerces.
// JSON.parse("42") === 42 (valid)
// JSON.parse("true") === true (valid)
// JSON.parse("null") === null (valid)
// JSON.parse(undefined) // throws SyntaxErrorJSON.stringify
JSON.stringify converte um valor JavaScript numa string JSON. Funções, Symbols e undefined são omitidos (em objetos) ou viram null (em arrays). BigInt lança TypeError — converta-o para string primeiro. Use o terceiro argumento (espaço) para formatação bonita.
// Serialize a JavaScript value to a JSON string.
const obj = { name: "Alice", age: 30 };
const json = JSON.stringify(obj);
// '{"name":"Alice","age":30}'
// Pretty-print with 2-space indent:
JSON.stringify(obj, null, 2);
// {
// "name": "Alice",
// "age": 30
// }
// Functions, Symbols, and undefined are omitted.
// BigInt throws; use a replacer or String() first.Função reviver
O reviver do JSON.parse transforma valores durante a interpretação. É chamado de baixo para cima para cada par chave/valor (incluindo a raiz, com chave ''). Retorne o valor transformado, ou undefined para omitir a propriedade. Útil para parse de datas, BigInt e tipos personalizados.
// JSON.parse accepts a 'reviver' to transform values.
const json = '{"date":"2024-01-15","count":"42"}';
const obj = JSON.parse(json, (key, value) => {
if (key === "date") return new Date(value);
if (key === "count") return Number(value);
return value;
});
// obj.date is a Date object; obj.count is a number.
// Reviver is called bottom-up for every key, including the root.Função replacer
O replacer do JSON.stringify filtra ou transforma valores durante a serialização. Como função, é chamado para cada chave — retorne undefined para omitir uma propriedade. Como array, atua como uma allowlist de chaves a incluir. Útil para censurar segredos e selecionar campos.
// JSON.stringify accepts a 'replacer' to filter/transform.
const obj = { name: "Alice", password: "secret", age: 30 };
// Replacer as a function:
const safe = JSON.stringify(obj, (key, value) => {
if (key === "password") return undefined; // omit
return value;
});
// '{"name":"Alice","age":30}'
// Replacer as an array (allowlist of keys):
JSON.stringify(obj, ["name", "age"]);
// '{"name":"Alice","age":30}'Formatação bonita
Passe um argumento de espaço ao JSON.stringify para formatação bonita: um número (profundidade de indentação) ou uma string (por exemplo, '\t'). Para ordem de chaves estável (útil para hashing ou assinatura), ordene as chaves antes de serializar. Combine com um replacer para filtrar campos enquanto formata.
const obj = { name: "Alice", age: 30 };
// Compact (default):
JSON.stringify(obj);
// '{"name":"Alice","age":30}'
// 2-space indent:
JSON.stringify(obj, null, 2);
// Tab indent:
JSON.stringify(obj, null, "\t");
// Combine replacer and indent:
JSON.stringify(obj, ["name", "age"], 2);
// To insert a stable key order, sort keys first:
const sorted = Object.keys(obj).sort()
.reduce((acc, k) => (acc[k] = obj[k], acc), {});
JSON.stringify(sorted, null, 2);Tratamento de erros
JSON.parse lança SyntaxError em entrada inválida — sempre envolva em try/catch para dados não confiáveis. Causas comuns: vírgulas finais, aspas simples, comentários ou entrada truncada. Para JSON muito grande ou profundamente aninhado, considere um parser de streaming ou limite de profundidade para prevenir negação de serviço.
// Always wrap JSON.parse in try/catch for untrusted input.
function safeParse(str) {
try {
return { ok: true, value: JSON.parse(str) };
} catch (e) {
return { ok: false, error: e.message };
}
}
// Common errors:
// SyntaxError: Unexpected token
// SyntaxError: Unexpected end of JSON input
// (no undefined/NaN/Infinity accepted)
// For deeply nested untrusted JSON, limit depth to avoid DoS.
// Consider a streaming parser for very large files.Interpretação em Python
json.loads
json.loads interpreta uma string JSON em objetos Python. Objetos JSON viram dicts, arrays viram lists, strings viram str, números viram int ou float automaticamente, true/false viram True/False, e null vira None. 'loads' significa 'load string'.
import json
json_str = '{"name": "Alice", "age": 30}'
data = json.loads(json_str)
print(data["name"]) # Alice
print(data["age"]) # 30
# loads = "load string"
# Returns Python objects: dict, list, str, int/float, bool, None
# JSON true/false/null -> Python True/False/None
# JSON numbers -> int or float (auto)json.dumps
json.dumps serializa um objeto Python numa string JSON. Use indent para formatação bonita, ensure_ascii=False para manter caracteres Unicode (em vez de escapes \uXXXX), e sort_keys=True para saída estável. True/False/None do Python mapeiam para true/false/null do JSON.
import json
data = {"name": "Alice", "age": 30, "active": True}
# Compact:
json.dumps(data)
# '{"name": "Alice", "age": 30, "active": true}'
# Pretty-printed:
json.dumps(data, indent=2, ensure_ascii=False)
# {
# "name": "Alice",
# "age": 30,
# "active": true
# }
# ensure_ascii=False keeps Unicode characters readable.
# sort_keys=True produces stable output.Interpretando arquivos
Use json.load (objeto de arquivo) e json.dump (objeto de arquivo) para arquivos; json.loads e json.dumps para strings. Sempre abra arquivos com encoding='utf-8' para evitar os padrões da plataforma. Para arquivos grandes, considere ijson (streaming) ou orjson (mais rápido) para melhor desempenho.
import json
# Read from a file:
with open("data.json", "r", encoding="utf-8") as f:
data = json.load(f)
# Write to a file:
with open("out.json", "w", encoding="utf-8") as f:
json.dump(data, f, indent=2, ensure_ascii=False)
# load/dump work on file objects; loads/dumps work on strings.
# Always specify encoding="utf-8" for portability.Encoders personalizados
Herde de json.JSONEncoder e sobrescreva default() para serializar tipos que o JSON não suporta nativamente (datetime, set, Decimal, classes personalizadas). Retorne uma representação serializável em JSON. Para decodificação, escreva um hook personalizado (object_hook) para reverter a transformação.
import json
from datetime import datetime, date
class CustomEncoder(json.JSONEncoder):
def default(self, obj):
if isinstance(obj, (datetime, date)):
return obj.isoformat()
if isinstance(obj, set):
return sorted(obj)
return super().default(obj)
data = {"now": datetime.now(), "tags": {"a", "b"}}
json.dumps(data, cls=CustomEncoder)
# '{"now": "2024-...", "tags": ["a", "b"]}'
# The default() method is called for objects json can't serialize.Tratamento de erros
json.loads lança json.JSONDecodeError em entrada inválida, com info de linha/coluna. Causas comuns: vírgulas finais, aspas simples, comentários, NaN/Infinity (rejeitados por padrão) e caracteres de controle em strings. Use parse_constant para tratar NaN/Infinity/-Infinity se necessário.
import json
def safe_loads(s):
try:
return {"ok": True, "value": json.loads(s)}
except json.JSONDecodeError as e:
return {"ok": False, "error": str(e), "line": e.lineno, "col": e.colno}
# json.JSONDecodeError gives line and column of the error.
# Common causes: trailing commas, single quotes, comments,
# NaN/Infinity (rejected by default), control chars in strings.
# To allow NaN/Infinity (non-standard):
json.loads('{"x": NaN}', parse_constant=lambda x: None) # or float(x)Trabalhando com Decimal e DateTime
Por padrão, json interpreta os números como float, perdendo precisão para decimais como dinheiro. Passe parse_float=Decimal para manter a precisão, e serialize com um hook default que converta Decimal de volta (para str para preservar a precisão, ou float se a perda for aceitável). Use str para representação exata de dinheiro.
import json
from decimal import Decimal
from datetime import datetime
# Decimal: parse_float keeps precision (default would lose it)
data = json.loads('{"price": 19.99}', parse_float=Decimal)
print(data["price"]) # Decimal('19.99')
print(data["price"] + Decimal("0.01")) # 20.00 exact
# Serialize Decimal back:
def encode(obj):
if isinstance(obj, Decimal):
return float(obj) # or str(obj) to keep precision
raise TypeError
json.dumps({"price": Decimal("19.99")}, default=encode)
# parse_float=float is the default; use Decimal for money.Interpretação em Java
Básico do Jackson
Jackson é a biblioteca JSON Java mais popular. ObjectMapper.readValue interpreta JSON em POJOs; writeValueAsString os serializa. Adicione jackson-databind (mais jackson-core e jackson-annotations) como dependências. Jackson é rápido, maduro e integra-se ao Spring Boot por padrão.
import com.fasterxml.jackson.databind.ObjectMapper;
ObjectMapper mapper = new ObjectMapper();
// Parse JSON to a Java object:
String json = "{\"name\":\"Alice\",\"age\":30}";
User user = mapper.readValue(json, User.class);
// Serialize a Java object:
String out = mapper.writeValueAsString(user);
// Pretty-print:
String pretty = mapper.writerWithDefaultPrettyPrinter()
.writeValueAsString(user);
// Jackson is the de facto JSON library for Java.
// Add: com.fasterxml.jackson.core:jackson-databindBásico do Gson
Gson é a biblioteca JSON do Google, mais simples que Jackson para uso básico. Gson.fromJson interpreta; toJson serializa. Use GsonBuilder para opções (formatação bonita, serialização de null, adapters personalizados). Adicione com.google.code.gson:gson como dependência. Gson é comum no Android.
import com.google.gson.Gson;
Gson gson = new Gson();
// Parse:
User user = gson.fromJson(json, User.class);
// Serialize:
String out = gson.toJson(user);
// Pretty-print:
Gson pretty = new GsonBuilder().setPrettyPrinting().create();
String s = pretty.toJson(user);
// Gson (by Google) is simpler than Jackson for basic use.
// Add: com.google.code.gson:gsonModelo de árvore JsonNode
O JsonNode do Jackson é um modelo de árvore para navegar no JSON sem um POJO. Use get() (retorna null se ausente) ou path() (retorna um 'nó ausente' seguro para encadear). asText/asInt/asBoolean têm overloads com valor padrão. Útil quando o schema é desconhecido ou varia.
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
ObjectMapper mapper = new ObjectMapper();
JsonNode root = mapper.readTree(json);
String name = root.get("name").asText(); // "Alice"
int age = root.get("age").asInt(); // 30
JsonNode hobbies = root.get("hobbies"); // array
for (JsonNode h : hobbies) {
System.out.println(h.asText());
}
// get() returns null for missing keys; path() returns a
// 'missing node' that you can chain safely.
String city = root.path("address").path("city").asText("unknown");Desserialização personalizada
Um JsonDeserializer personalizado trata codificações JSON não padrão (por exemplo, '$19.99' para dinheiro). Anote um campo com @JsonDeserialize(using = ...) ou registre um SimpleModule para um tipo. Use JsonSerializer para serialização personalizada. Isso mantém seus POJOs livres de lógica de interpretação.
import com.fasterxml.jackson.databind.*;
import com.fasterxml.jackson.core.*;
import java.io.IOException;
public class MoneyDeserializer extends JsonDeserializer<Double> {
@Override
public Double deserialize(JsonParser p, DeserializationContext ctxt)
throws IOException {
String s = p.getText(); // e.g. "$19.99"
return Double.parseDouble(s.replaceAll("[^0-9.]", ""));
}
}
// Annotate the field:
// @JsonDeserialize(using = MoneyDeserializer.class)
// public double price;
// Or register a module for a type.API de streaming
A API de streaming do Jackson (JsonParser/JsonGenerator) lê e escreve JSON token a token com memória constante — ideal para arquivos enormes. Você controla o loop de interpretação e pode pular subárvores com skipChildren(). Pareie com o modelo de árvore ou POJO para as partes que realmente precisa.
import com.fasterxml.jackson.core.*;
// Jackson streaming: low memory, fast, for huge files.
JsonFactory f = new JsonFactory();
try (JsonParser p = f.createParser(new File("huge.json"))) {
while (p.nextToken() != JsonToken.END_OBJECT) {
String field = p.getCurrentName();
if ("name".equals(field)) {
p.nextToken();
System.out.println(p.getText());
}
// skip complex values you don't need:
// p.skipChildren();
}
}
// Use streaming for files that won't fit in memory.Interpretação em PHP
json_encode
json_encode serializa um valor PHP para JSON. Arrays PHP viram objetos JSON (associativos) ou arrays (sequenciais). Flags comuns: JSON_PRETTY_PRINT, JSON_UNESCAPED_UNICODE (mantém Unicode legível), JSON_UNESCAPED_SLASHES (não escapa /). Combine flags com o operador |.
<?php
$data = ["name" => "Alice", "age" => 30, "active" => true];
// Compact (default):
$json = json_encode($data);
// {"name":"Alice","age":30,"active":true}
// Pretty-print:
$pretty = json_encode($data, JSON_PRETTY_PRINT);
// Keep Unicode readable (don't escape to \uXXXX):
$unicode = json_encode($data, JSON_UNESCAPED_UNICODE);
// Combine flags with |:
json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE
| JSON_UNESCAPED_SLASHES);json_decode
json_decode interpreta JSON em PHP. O segundo argumento controla o resultado: true retorna arrays associativos, false (padrão) retorna objetos stdClass. Escolha conforme seu estilo de acesso ($arr['key'] vs $obj->key). Arrays PHP com chaves não sequenciais viram objetos JSON.
<?php
$json = '{"name":"Alice","age":30,"hobbies":["reading"]}';
// Default: returns associative array OR object (stdClass)
$data = json_decode($json);
echo $data->name; // Alice
// Force associative array:
$arr = json_decode($json, true);
echo $arr["name"]; // Alice
// The second argument (assoc) controls array vs object.
// PHP objects become stdClass instances by default.Tratamento de erros
O json_decode do PHP não lança exceção por padrão — verifique json_last_error() e json_last_error_msg() depois de interpretar. Passe JSON_THROW_ON_ERROR (PHP 7.3+) para que lance JsonException, o que é mais limpo. Erros comuns: vírgulas finais, aspas simples e UTF-8 inválido.
<?php
$json = '{invalid json}';
$data = json_decode($json);
if (json_last_error() !== JSON_ERROR_NONE) {
echo "Parse error: " . json_last_error_msg();
// e.g., "Syntax error"
}
// PHP does not throw on JSON errors; check json_last_error().
// Common errors: trailing comma, single quotes, invalid UTF-8.
// To throw exceptions instead:
try {
$data = json_decode($json, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
echo $e->getMessage();
}Pretty print e flags
Flags comuns do json_encode: JSON_PRETTY_PRINT (indentação), JSON_UNESCAPED_UNICODE (mantém não-ASCII legível), JSON_UNESCAPED_SLASHES (não escapa /), JSON_NUMERIC_CHECK (converte strings numéricas em números), JSON_THROW_ON_ERROR (lança em falha). Combine com |.
<?php
$data = ["path" => "C:\\Users", "url" => "https://x.com/"];
// Default escapes / and non-ASCII:
json_encode($data);
// {"path":"C:\\Users","url":"https:\/\/x.com\/"}
// Cleaner output:
json_encode($data, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE
| JSON_PRETTY_PRINT);
// {
// "path": "C:\\Users",
// "url": "https://x.com/"
// }
// JSON_NUMERIC_CHECK converts numeric strings to numbers:
json_encode(["id" => "42"], JSON_NUMERIC_CHECK); // {"id":42}Serialização personalizada
Implemente JsonSerializable e defina jsonSerialize() para controlar como um objeto é codificado. Essa é a forma mais limpa de censurar campos (por exemplo, omitir password), renomear chaves ou computar valores derivados durante a serialização. A função retorna qualquer estrutura serializável em JSON.
<?php
class User implements JsonSerializable {
public $name;
public $password;
public function __construct($name, $password) {
$this->name = $name;
$this->password = $password;
}
public function jsonSerialize(): mixed {
return [
"name" => $this->name,
// omit password for security
];
}
}
echo json_encode(new User("Alice", "secret"));
// {"name":"Alice"}
// JsonSerializable lets the class control its JSON form.Especificação JSON:API
Estrutura do documento
JSON:API é uma especificação para construir APIs JSON consistentes. Um documento tem um objeto de versão 'jsonapi' de nível superior, um recurso primário 'data', recursos relacionados 'included' opcionais, 'meta' para informação não padrão, 'links' para paginação e 'errors' para falhas. O media type é application/vnd.api+json.
{
"jsonapi": { "version": "1.1" },
"data": {
"type": "articles",
"id": "1",
"attributes": {
"title": "JSON:API Basics"
},
"relationships": {
"author": { "data": { "type": "people", "id": "9" } }
}
},
"included": [
{ "type": "people", "id": "9", "attributes": { "name": "Jane" } }
]
}
// JSON:API is a convention for building JSON APIs.
// Top-level keys: jsonapi, data, errors, meta, links, included.Resource objects
Um resource object JSON:API tem um 'type' (o tipo de recurso) e um 'id' (um identificador em string), além de 'attributes' (os dados) e opcionalmente 'relationships' (vínculos a outros recursos) e 'links' (URLs como self). Os IDs devem ser strings. Type e id não podem aparecer em attributes.
{
"data": {
"type": "articles",
"id": "1",
"attributes": {
"title": "Hello",
"published": true,
"views": 42
},
"links": {
"self": "/articles/1"
}
}
}
// Every resource has a 'type' (string) and 'id' (string).
// 'attributes' holds data; 'relationships' holds links to others.
// 'id' and 'type' MUST NOT appear inside attributes.Relationships
Relationships ligam um recurso a outros via resource identifier objects ({type, id}). Relacionamentos to-one usam um único identificador; to-many usam um array. O objeto 'links' fornece 'self' (a URL do relacionamento) e 'related' (a URL do recurso relacionado) para navegação.
{
"data": {
"type": "articles",
"id": "1",
"relationships": {
"author": {
"data": { "type": "people", "id": "9" },
"links": {
"self": "/articles/1/relationships/author",
"related": "/articles/1/author"
}
},
"tags": {
"data": [
{ "type": "tags", "id": "1" },
{ "type": "tags", "id": "2" }
]
}
}
}
}
// to-one: data is a single resource identifier.
// to-many: data is an array of resource identifiers.Meta e links
'meta' carrega informação não padrão, como contagens totais, rate limits ou avisos. 'links' fornece navegação hypermedia: self, first, prev, next, last para paginação, além de URLs relacionadas. Use null para um link ausente (por exemplo, prev na primeira página).
{
"meta": {
"totalPages": 5,
"currentPage": 1,
"rateLimit": 100
},
"links": {
"self": "/articles?page=1",
"first": "/articles?page=1",
"prev": null,
"next": "/articles?page=2",
"last": "/articles?page=5"
},
"data": [ /* ... */ ]
}
// meta: non-standard metadata (counts, rate limits, etc.).
// links: pagination and resource URLs.Erros
Documentos de erro JSON:API têm um array 'errors' de nível superior (e nenhum 'data'). Cada objeto de erro tem campos opcionais: id, status (código HTTP como string), code (específico da aplicação), title (resumo curto), detail (explicação humana), source (ponteiro para o campo problemático via JSON Pointer) e meta.
{
"errors": [
{
"id": "err-123",
"status": "404",
"code": "NOT_FOUND",
"title": "Resource Not Found",
"detail": "Article 99 does not exist.",
"source": { "pointer": "/data/attributes/id" },
"meta": { "requestId": "abc-9" }
}
]
}
// Errors is an array of error objects.
// status: HTTP status string; code: app-specific code.
// source.pointer: JSON Pointer to the offending field.JSON5
Recursos do JSON5
JSON5 é um superconjunto do JSON desenhado para configuração escrita por humanos. Adiciona comentários, strings sem aspas/entre aspas simples, vírgulas finais, números hex/Infinity/NaN e formatos numéricos relaxados. JSON5 não é JSON padrão — use um parser JSON5 (pacote npm json5) e converta para JSON para intercâmbio.
// JSON5 is a superset of JSON with friendlier syntax.
{
// line comments
/* block comments */
unquotedKey: "ok", // unquoted keys
"with space": "ok", // quoted keys still allowed
singleQuote: 'single', // single-quoted strings
trailing: [1, 2, 3,], // trailing commas
hex: 0x1F, // hexadecimal numbers
inf: Infinity, // Infinity, -Infinity, NaN
leadingDot: .5, // leading decimal point
trailingDot: 5., // trailing decimal point
plus: +5, // leading plus
}
// JSON5 is NOT standard JSON—use a JSON5 parser.Comentários
JSON5 suporta tanto comentários de linha // quanto comentários de bloco /* */, que o JSON padrão proíbe. Isso torna o JSON5 ideal para arquivos de configuração escritos por humanos. O settings.json do VS Code e o tsconfig.json do TypeScript usam JSONC (JSON com comentários), um subconjunto parecido, mas um pouco diferente.
{
// Single-line comment (like JS)
"name": "Alice",
/* Block comment
spanning multiple lines */
"age": 30,
"active": true // end-of-line comment
}
// Standard JSON rejects comments.
// JSON5 supports // and /* */ comments everywhere.
// VS Code's settings.json and tsconfig.json use JSONC (a subset).Vírgulas finais
JSON5 permite vírgulas finais após o último elemento de objetos e arrays. O JSON padrão as rejeita. Vírgulas finais reduzem o ruído de diff ao adicionar ou reordenar campos (cada linha pode terminar com vírgula). Muitas linguagens e formatos de configuração modernos agora permitem isso.
{
"a": 1,
"b": 2,
"c": 3, // <-- trailing comma OK in JSON5
}
// Arrays too:
[1, 2, 3,]
// Standard JSON rejects trailing commas.
// JSON5 allows them, reducing diff noise when adding fields.Strings sem aspas e com aspas simples
JSON5 permite chaves identificadoras sem aspas (casando [A-Za-z_$][A-Za-z0-9_$]*) e tanto strings com aspas simples quanto duplas. Dentro de uma string com aspas simples, escape ' como \'; dentro de uma com aspas duplas, escape " como \". Isso espelha a sintaxe de literal de objeto JavaScript por legibilidade.
{
unquoted: "value", // unquoted identifier key
"quoted key": "value", // quoted key (for special chars)
single: 'single-quoted', // single-quoted string value
mixed: 'it\'s ok', // escape single quote inside
double: "she said \"hi\"", // escape double quote inside
}
// Unquoted keys must be valid identifiers ([A-Za-z_$][A-Za-z0-9_$]*).
// Single and double quotes are both allowed for strings.Números e strings (estendidos)
JSON5 estende os números: hexadecimal (0xFF), pontos decimais inicial/final (.5, 5.), mais à esquerda (+5) e as palavras-chave Infinity, -Infinity e NaN. Cada um é rejeitado pelo JSON padrão. Strings JSON5 ainda usam sequências de escape (\n) para quebras de linha — não há strings multilinha soltas.
{
hex: 0xFF, // hexadecimal
leadingDot: .5, // .5 instead of 0.5
trailingDot: 5., // 5. instead of 5.0
leadingPlus: +5, // +5 (standard JSON rejects +)
infinity: Infinity, // Infinity (not in standard JSON)
negativeInfinity: -Infinity,
nan: NaN,
multiline: 'line1\nline2' // escape sequences like JSON
}
// JSON5 does NOT support real multi-line strings or bareword NaN.JSON Lines (JSONL)
Formato JSONL
JSON Lines (JSONL ou NDJSON) é um formato em que cada linha é um valor JSON separado e completo. Não há array envolvente. Isso o torna ideal para streaming, logs e datasets grandes: você pode processar linha a linha sem carregar o arquivo inteiro. Extensões: .jsonl, .ndjson.
// A JSON Lines file (.jsonl / .ndjson) is one JSON value per line:
{"name": "Alice", "age": 30}
{"name": "Bob", "age": 25}
{"name": "Carol", "age": 35}
// Rules:
// - Each line is a COMPLETE, valid JSON value.
// - Lines are separated by newlines (\n).
// - No enclosing [ ] array.
// - Each line is parsed independently.Lendo JSONL
Leia JSONL iterando as linhas e interpretando cada uma com JSON.parse/loads. Isso faz streaming do arquivo com memória constante — ideal para datasets enormes. Pule linhas em branco. No Node.js, use readline sobre um stream de arquivo; no Python, itere o objeto de arquivo diretamente. Não é preciso carregar o arquivo inteiro.
// JavaScript (Node.js) — line by line:
const fs = require("fs");
const readline = require("readline");
const rl = readline.createInterface({
input: fs.createReadStream("data.jsonl"),
crlfDelay: Infinity,
});
for await (const line of rl) {
if (!line.trim()) continue;
const obj = JSON.parse(line);
console.log(obj.name);
}
// Python:
// import json
// with open("data.jsonl") as f:
// for line in f:
// obj = json.loads(line)Escrevendo JSONL
Escreva JSONL serializando cada registro com JSON.stringify/dumps (compacto, sem indentação) e acrescentando uma quebra de linha. Use um stream gravável (Node) ou abra o arquivo em modo de escrita (Python) por eficiência. A forma compacta mantém as linhas curtas e interpretáveis; um registro por linha é a regra.
// JavaScript (Node.js):
const fs = require("fs");
const out = fs.createWriteStream("out.jsonl");
for (const obj of records) {
out.write(JSON.stringify(obj) + "\n");
}
out.end();
// Python:
// import json
// with open("out.jsonl", "w") as f:
// for obj in records:
// f.write(json.dumps(obj) + "\n")
// One JSON per line; compact form (no indent) is conventional.Casos de uso
JSONL brilha em arquivos de log, datasets grandes, dados de treino de ML, dumps de banco de dados e streams de eventos append-only. Cada linha é independente, então você pode acrescentar sem reescrever, retomar a interpretação após uma linha corrompida e processar em paralelo. Ferramentas como jq e pipes de shell funcionam naturalmente com ele.
// JSONL is ideal for:
// - log files (one event per line)
// - large datasets (streaming, append-only)
// - machine learning training data
// - database exports/imports
// - append-only event streams
// Example: log entry per line
{"ts": "2024-01-15T10:00:00Z", "level": "info", "msg": "started"}
{"ts": "2024-01-15T10:00:01Z", "level": "error", "msg": "failed"}
// Tools: jq, xargs, awk | json.loads — all work line-by-line.JSONL vs array JSON
Um array JSON envolve os registros em [ ] e exige carregar (ou fazer streaming com cuidado) o arquivo inteiro para interpretar. JSONL põe um registro por linha, habilitando streaming verdadeiro, acréscimo fácil e recuperação de linhas corrompidas. Para datasets grandes ou em crescimento, JSONL é quase sempre a escolha melhor.
// JSON Array (one big file):
[
{"name": "Alice"},
{"name": "Bob"},
{"name": "Carol"}
]
// JSONL (one per line):
{"name": "Alice"}
{"name": "Bob"}
{"name": "Carol"}
// JSON Array: must load whole file to parse; hard to append.
// JSONL: streamable, appendable, resumable; slightly more
// per-record overhead but far better for big files.Segurança
Riscos do JSONP
JSONP envolve JSON num callback JavaScript para que uma tag <script> possa buscar dados cross-origin, burlando a same-origin policy. Isso é perigoso: qualquer site pode ler a resposta, injeção de callback habilita XSS, e as requisições carregam os cookies da vítima. Use CORS em vez disso — JSONP é legado e inseguro.
// JSONP (JSON with Padding) bypasses same-origin policy
// by wrapping JSON in a script callback:
callbackHandler({"secret": "data"});
// Loaded via <script src="https://api.example.com/data?callback=callbackHandler">
// RISKS:
// - Any site can include the URL and read the response.
// - XSS if the callback name is attacker-controlled.
// - CSRF: the request is made with the victim's cookies.
// MODERN ALTERNATIVE: use CORS instead of JSONP.
// JSONP is legacy—avoid it for new APIs.Prevenção de XSS
JSON embutido em tags <script> HTML pode causar XSS: a string '</script>' encerra o script cedo. Além disso, U+2028 e U+2029 (separadores de linha/parágrafo) são válidos em strings JSON, mas quebram o JavaScript. Escape <, >, &, U+2028, U+2029 ao embutir JSON em HTML, ou use uma biblioteca como serialize-javascript.
// JSON itself is data, not executable—BUT embedding it in
// HTML can cause XSS if not careful.
// BAD: output JSON inside <script> without escaping:
// <script>
// var data = {"name": "</script><script>alert(1)</script>"};
// </script>
// GOOD: escape < and > (and &) when embedding in HTML:
const safe = JSON.stringify(data)
.replace(/</g, "\\u003c")
.replace(/>/g, "\\u003e")
.replace(/&/g, "\\u0026")
.replace(/\u2028/g, "\\u2028")
.replace(/\u2029/g, "\\u2029");
// Or use a library: js-xss, serialize-javascript.Prototype pollution
Prototype pollution ocorre quando JSON não confiável contendo chaves como '__proto__' ou 'constructor' é mesclado em objetos, envenenando Object.prototype e afetando os objetos. Defesas: use Object.create(null), bloqueie chaves perigosas, prefira Map para dados não confiáveis e mantenha as bibliotecas de mesclagem atualizadas.
// Merging untrusted JSON into objects can pollute prototypes:
const evil = JSON.parse('{"__proto__": {"isAdmin": true}}');
// BAD merge (Object.assign does NOT pollute, but some libs do):
// function merge(target, src) {
// for (const k in src) target[k] = src[k];
// }
// Attackers can set Object.prototype.isAdmin = true,
// affecting ALL objects.
// Defenses:
// - Use Object.create(null) for parsed objects.
// - Block keys like __proto__, constructor, prototype.
// - Use Map instead of plain objects for untrusted data.
// - Keep dependencies updated (some had merge() flaws).Injeção via JSON
O JSON em si resiste a injeção, mas construí-lo por concatenação de strings é perigoso — entrada do usuário pode romper a estrutura do JSON. Sempre use um serializador real (JSON.stringify). O mesmo vale a jusante: use consultas SQL parametrizadas, execFile com arrays de argumentos e engines de template com escapamento HTML.
// JSON itself is not injectable, but building JSON by
// concatenation is dangerous:
// BAD: string concatenation
// const json = '{"name": "' + userInput + '"}';
// // userInput = '"); drop table; //' -> breaks out
// GOOD: always use a real serializer
const json = JSON.stringify({ name: userInput });
// For SQL: use parameterized queries, not JSON interpolation.
// For shell: use execFile with arg arrays, not string concat.
// For HTML: use textContent or a templating engine that escapes.DoS via JSON grande ou profundo
DoS baseado em JSON: arquivos enormes esgotam a RAM, aninhamento profundo estoura a pilha do parser, e estruturas patológicas (o análogo JSON de 'billion laughs') inflacionam uma entrada pequena. Defesas: limite o tamanho do corpo da requisição no proxy, limite a profundidade de interpretação, use parsers de streaming para entradas grandes e defina timeouts.
// Attackers can craft JSON to exhaust memory or CPU:
//
// 1. Huge file: 1 GB of '[1,1,1,...]' to exhaust RAM.
// 2. Deep nesting: '{"a":{"a":{"a":...}}}' (10000 levels)
// to overflow the parser's stack.
// 3. 'Billion laughs': nested entity expansion (XML-era,
// but JSON analogs exist with $ref in some libs).
// 4. Many keys: 10 million keys in one object.
// Defenses:
// - Cap request body size at the server/reverse proxy.
// - Limit parsing depth (Ajv, fast-json-parse options).
// - Use streaming parsers (stream-json, oboe) for big input.
// - Set timeouts on parsing.Práticas seguras de interpretação
Interpretação segura de JSON: sempre use JSON.parse (nunca eval), valide contra um schema (Ajv, jsonschema) antes de usar, limite profundidade e contagem de chaves, desabilite chaves __proto__, e considere interpretar entrada não confiável num Web Worker ou sandbox. JSON.parse em si é seguro quanto a execução de código; os riscos estão em como você usa os dados interpretados.
// 1. Validate with a schema before using untrusted JSON.
const Ajv = require("ajv");
const ajv = new Ajv({ allErrors: true });
const validate = ajv.compile(schema);
if (!validate(data)) throw new Error(ajv.errorsText(validate.errors));
// 2. Limit depth and key count when parsing.
// 3. Use reviver/replacer to coerce types safely.
// 4. Never eval() or Function('return ' + json) — use JSON.parse.
// 5. Disable dangerous features (e.g., __proto__ keys).
// 6. Parse untrusted JSON in a sandbox or worker if possible.
// JSON.parse is safe; eval is NOT.Boas práticas e ferramentas
Schema primeiro
Desenhe APIs schema-first: defina um JSON Schema, gere tipos de linguagem a partir dele (typescript-json-schema, quicktype, jsonschema2pojo), e valide requisições/respostas em runtime. Isso captura violações de contrato cedo, habilita geração de código e serve de documentação viva.
// Define a JSON Schema before shipping an API.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": ["id", "name"],
"properties": {
"id": { "type": "integer" },
"name": { "type": "string", "minLength": 1, "maxLength": 100 }
},
"additionalProperties": false
}
// Generate types from the schema (TypeScript, Java, Go, ...).
// Validate both requests and responses against the schema.
// Publish the schema for clients (OpenAPI, JSON Schema).Nomenclatura consistente
Escolha uma convenção de nomenclatura para as chaves e aplique-a consistentemente: camelCase (a maioria das APIs JSON e JS), snake_case (backends Python/Ruby, APIs do Google) ou PascalCase (.NET). Misturar estilos é confuso. Se front e back diferirem, converta numa única fronteira, em vez de misturar no schema.
// Pick ONE naming convention and apply it everywhere.
// camelCase (most JSON APIs, JavaScript ecosystem):
{ "firstName": "Alice", "lastName": "Smith" }
// snake_case (Python/Ruby backends, many Google APIs):
{ "first_name": "Alice", "last_name": "Smith" }
// kebab-case (rare in JSON, common in URLs/config):
{ "first-name": "Alice" }
// PascalCase (rare in JSON keys, common in C#/.NET types):
{ "FirstName": "Alice" }
// Avoid mixing; convert at the boundary if the front/back differ.Versionamento
Versione APIs desde o primeiro dia: no path da URL (/v1/), num campo de versão no payload, no header Accept (media type) ou num namespace (JSON-LD @context). Mudanças aditivas (novos campos opcionais) costumam não quebrar; aumente a versão para campos removidos/renomeados ou semântica alterada.
// 1. Version in the URL path:
// https://api.example.com/v1/users
// 2. Version field in the payload:
{ "version": "1.0", "data": { ... } }
// 3. Accept header / media type:
// Accept: application/vnd.example.v1+json
// 4. Namespace the JSON (JSON-LD, JSON:API 'type'):
{ "@context": "https://schema.org/v1", ... }
// Plan for evolution: add optional fields freely, but bump
// the version for breaking changes (removed/renamed fields,
// changed semantics or types).Codificação (UTF-8)
UTF-8 é a codificação padrão e a única amplamente recomendada para JSON. Salve arquivos como UTF-8 sem BOM (alguns parsers lidam mal com ele), defina Content-Type com charset=utf-8 e defina Content-Length em bytes. Em Python, passe ensure_ascii=False para manter os caracteres Unicode legíveis em vez de escapes \uXXXX.
// Always use UTF-8 for JSON.
// - Save files as UTF-8 (no BOM).
// - Set Content-Type: application/json; charset=utf-8.
// - Set Content-Length in bytes (not characters).
// In Node.js:
res.setHeader("Content-Type", "application/json; charset=utf-8");
res.end(JSON.stringify(data));
// In Python:
import json
with open("out.json", "w", encoding="utf-8") as f:
json.dump(data, f, ensure_ascii=False)
// ensure_ascii=False keeps Unicode readable in the file.Dicas de desempenho
Por desempenho: faça streaming de JSON grande (ijson, stream-json, Jackson streaming) em vez de bufferizar; use serializadores rápidos (orjson, fast-json-stringify); transmita compacto e comprima com gzip/brotli sobre HTTP; evite aninhamento profundo e arrays enormes; cacheie resultados interpretados para evitar reinterpretação.
// 1. Stream large JSON instead of buffering it all.
// - Node: stream-json, JSONStream
// - Python: ijson
// - Java: Jackson streaming API
// 2. Use a fast serializer:
// - Node: fast-json-stringify (schema-based), orjson (Python)
// - Compile serializers from a schema for hot paths.
// 3. Compact JSON for transmission; pretty only for humans.
// 4. Avoid deep nesting and huge arrays when possible.
// 5. Compress with gzip/brotli over HTTP (huge savings).
// 6. Cache parsed results; don't re-parse the same payload.Ferramentas e validadores
Ferramentas para trabalhar com JSON: validadores online (jsonlint.com, jsonschemavalidator.net), ferramentas de CLI (jq para consultar/formatar, jsonschema para validação), suporte de editor (VS Code e JetBrains têm validação embutida de JSON + schema) e geradores de código (quicktype gera tipos TypeScript/Java/Go/etc. a partir de JSON ou de um schema).
// Online validators:
// - https://jsonlint.com
// - https://jsonformatter.org
// - https://www.jsonschemavalidator.net
// CLI tools:
// - jq (filter, query, format JSON on the command line)
// - jaq (Rust jq clone, faster)
// - jsonschema (Python CLI for schema validation)
// - ajv (Node CLI/library for JSON Schema)
// Editor support:
// - VS Code: built-in JSON + schema validation
// - JetBrains: built-in JSON + schema support
// - vim/emacs: plugins available
// Schema tools:
// - quicktype (generate types from JSON)
// - typescript-json-schema
// - jsonschema2pojo (Java)Snippets de JSON relacionados
Copy-paste ready code for common tasks.
Data Types
The seven JSON value types.
Nested Objects
Objects within objects for hierarchical data.
Arrays
Lists of mixed and homogeneous values.
Schema Validation
Validate structure with JSON Schema.
JSONPath
Query expressions for locating nodes.
Merge Patch (RFC 7386)
Partially update JSON documents.
JSON Pointer (RFC 6901)
Address a specific value by path.
Streaming (NDJSON)
Newline-delimited JSON for streaming.
Was this helpful?