Transformação e criação de objetos JSON com jq

O JSON bruto de APIs ou arquivos de registro raramente tem exatamente o formato de que você precisa. Você pode receber um objeto grande, mas querer apenas campos específicos; também pode precisar renomear chaves, achatar estruturas aninhadas ou criar uma carga completamente nova para enviar a outro serviço.

jq é um processador de JSON leve e poderoso para a linha de comando que possibilita essas transformações em um único fluxo. Nesta lição, você aprenderá as três técnicas essenciais para reorganizar dados:

• Construção de objetos — criar um novo objeto JSON do zero
• map — aplicar uma transformação a cada elemento de uma matriz
• to_entries / from_entries — tratar os pares chave-valor de um objeto como uma matriz para poder filtrá-los e reconstruí-los

Todos os exemplos pressupõem que o jq esteja instalado (apt install jq / brew install jq).

O recurso mais fundamental do jq é a construção de objetos: envolver expressões em {} para criar um novo objeto JSON. Você escolhe quais campos incluir e como chamá-los.

Sintaxe:

• { newKey: .existingField } — renomeia um campo
• { name, age } — forma abreviada quando a nova chave corresponde ao nome do campo
• { total: (.price * .qty) } — calcula um valor diretamente na expressão

O trecho abaixo lê um JSON de produto e produz uma estrutura mais enxuta com um campo subtotal calculado.

O JSON do mundo real costuma ser aninhado. O jq permite acessar caminhos aninhados dentro de um construtor de objetos, achatando a estrutura ao mesmo tempo.

Use a notação de caminho com pontos dentro da expressão de valor do construtor:

• { city: .address.city }
• { lat: .location.coords.lat }

O exemplo abaixo recebe um registro de usuário profundamente aninhado e produz um resumo plano, adequado para uma linha de cabeçalho CSV ou para o corpo de uma requisição de API.

map(expr) é o equivalente do jq a um for-each: aplica expr a cada elemento de uma matriz de entrada e retorna uma nova matriz com o mesmo comprimento.

Pontos principais:

• map(expr) é uma abreviação de [.[] | expr]
• A expressão interna pode ser qualquer filtro do jq — incluindo a construção de objetos
• Encadeie com select() para filtrar antes de transformar

O trecho processa uma lista de pedidos, mantendo apenas os campos necessários para um manifesto de envio.

Dentro de map, você pode calcular novos valores, converter tipos e combinar campos — não apenas copiá-los. Padrões comuns incluem:

• Interpolação de strings: "\(.first) \(.last)"
• Aritmética: (.price * 1.2 | round) para um acréscimo de 20%
• Condicionais: if .score >= 90 then "A" else "B" end

O exemplo abaixo enriquece uma lista de funcionários adicionando um fullName calculado e um rótulo de seniority com base nos anos de experiência.

to_entries converte um objeto JSON em uma matriz de pares {key, value}. Isso permite usar operações de matriz (map, select, sort) nos campos de um objeto — algo que não é possível fazer diretamente em um objeto.

Exemplo de transformação:

• Entrada: {"a": 1, "b": 2}
• Saída: [{"key": "a", "value": 1}, {"key": "b", "value": 2}]

A operação inversa é from_entries, que transforma essa matriz novamente em um objeto. Juntas, elas formam o padrão to_entries | map(...) | from_entries para transformações no nível do objeto.

Um dos usos mais práticos de to_entries é filtrar dinamicamente quais chaves manter ou descartar com base no próprio nome da chave — algo que a construção de objetos não pode fazer quando você não conhece os nomes das chaves antecipadamente.

Padrão:

• to_entries | map(select(.key | test("regex"))) | from_entries
• to_entries | map(select(.key != "secret")) | from_entries

O trecho abaixo remove todas as chaves que começam com um sublinhado (campos internos/privados) antes de encaminhar um objeto de configuração para um serviço externo.

A construção de objetos renomeia chaves quando você conhece seus nomes no momento da escrita. to_entries permite renomear chaves programaticamente — por exemplo, convertendo camelCase para snake_case ou adicionando um prefixo.

Dentro de map, você atualiza o campo .key de cada entrada e depois usa um pipe para from_entries:

• map(.key |= gsub("(?<=[a-z])(?=[A-Z])"; "_") | .key |= ascii_downcase) — camelCase para snake_case
• map(.key |= "app_" + .) — adiciona um prefixo a cada chave

O exemplo adiciona o prefixo APP_ a todos os nomes de variáveis de ambiente para criar um espaço de nomes antes de injetá-los em um contêiner.

O padrão to_entries | map(...) | from_entries é tão comum que o jq fornece uma abreviação: with_entries(expr).

Ele é exatamente equivalente, mas mais conciso:

• with_entries(.value |= . * 2) — duplica cada valor numérico
• with_entries(select(.value != null)) — remove chaves com valores nulos
• with_entries(.key |= ascii_upcase) — converte todas as chaves para maiúsculas

O trecho remove todas as chaves cujo valor é null ou uma string vazia — uma etapa comum de limpeza antes de enviar uma requisição PATCH para uma API REST.

Transformações reais encadeiam várias operações do jq. Um fluxo típico para preparar uma carga de API pode:

1. Filtrar a matriz de entrada com map(select(...))
2. Reorganizar cada elemento com a construção de objetos
3. Adicionar campos calculados
4. Ordenar o resultado

O exemplo abaixo lê uma lista de métricas de servidores, mantém apenas os servidores com alto uso de CPU e produz uma carga compacta de alerta pronta para ser enviada por POST a um webhook.

O jq pode mesclar entradas e construir objetos provenientes de várias fontes JSON usando o operador de adição + e a vinculação de variáveis com as $var.

Padrões úteis:

• obj1 + obj2 — mescla dois objetos (o lado direito prevalece em conflitos de chaves)
• --argjson — passa um segundo documento JSON como variável
• $ENV — lê variáveis de ambiente diretamente dentro do jq

O trecho mescla uma configuração básica com substituições específicas do ambiente — um padrão comum para gerenciar configurações de aplicações seguindo os princípios dos 12 fatores em scripts do shell.

Você tem o seguinte objeto JSON e precisa remover todas as chaves cujo valor é menor que 0, produzindo um novo objeto apenas com valores não negativos. Qual expressão do jq realiza isso corretamente?

Entrada: {"a": 10, "b": -3, "c": 0, "d": 5}

Você aprendeu as técnicas essenciais para reorganizar JSON com jq:

• Construção de objetos {} — cria novos objetos escolhendo, renomeando e calculando campos a partir de uma entrada
• map(expr) — aplica qualquer transformação a cada elemento de uma matriz, incluindo a construção de objetos aninhados e select() para filtragem
• to_entries / from_entries — converte um objeto em uma matriz de pares {key, value}, permitindo operações de matriz nas chaves e nos valores, e depois converte novamente
• with_entries(expr) — a abreviação concisa para o fluxo completo to_entries → map → from_entries
• Mesclagem de objetos com + e --argjson para cargas provenientes de várias fontes

Esses blocos básicos se combinam: filtre com select, reorganize com a construção de objetos, enriqueça com campos calculados e encadeie tudo em uma única expressão jq legível. Dominar esses padrões significa que você pode manipular praticamente qualquer carga JSON diretamente no shell, sem escrever um script dedicado em Python ou Node.