Trabajar con JSON en la línea de comandos con jq

Objetivo

Extraer, filtrar o remodelar JSON proveniente de la respuesta de una API, una línea de registro o un archivo de configuración dentro de una tubería, sin escribir un programa desechable.

Requisitos previos

jq instalado; una entrada que sea JSON válido o un flujo de textos JSON; alguna idea de la forma de la entrada (jq 'keys', jq '.[0]' y jq 'paths' ayudan a explorarla).

Pasos

1. Confirmar que la entrada se analiza correctamente y ver su forma: jq . la imprime con formato legible; en entradas grandes, jq -c '.[0]' o jq 'keys' es más económico de leer.
2. Navegar: .foo.bar y .[0] indexan, .[] itera un arreglo o los valores de un objeto, .foo? suprime el error cuando la entrada no es un objeto. Encadenar filtros con |.
3. Filtrar y remodelar: .items[] | select(.status == "open") | {id, name}; map(f) aplica un filtro a cada elemento; to_entries, from_entries y with_entries(f) convierten entre objetos y listas de pares clave-valor; a // b da b cuando a produce solo null o false.
4. Pasar valores del shell con --arg name value (siempre una cadena) o --argjson name json (tipado) y usar $name en el filtro. El manual señala que --arg foo 123 vincula la cadena "123", no un número.
5. Elegir la forma de salida para el siguiente programa: -r (--raw-output) escribe las cadenas sin comillas; -c imprime JSON compacto en una sola línea; @tsv, @csv y @sh dan formato a los arreglos para su consumo separado por tabulaciones, en CSV o en shell POSIX; --raw-output0 separa las salidas con NUL cuando los valores pueden contener saltos de línea.
6. Manejar múltiples entradas: por defecto, el filtro se ejecuta una vez por cada texto JSON del flujo; -s (--slurp) los reúne en un único arreglo; -n (--null-input) ejecuta el filtro una sola vez con null como entrada, que es la forma de construir JSON desde cero: jq -n --arg a "$x" '{a: $a}'.
7. Hacer que la ausencia de datos falle: -e (--exit-status) fija el código de salida en 1 si la última salida es null o false, y en 4 si no se produjo ningún resultado válido; probarlo en los scripts en lugar de comprobar si hay una cadena vacía.

Resultado esperado

Una tubería de una sola línea que produce exactamente el campo o la estructura necesarios, correctamente citados para el siguiente programa, y un código de salida distinto de cero cuando faltan los datos.

Límites y base de verificación

La semántica sigue el manual de jq citado. jq carga por completo cada texto JSON a menos que se use --stream, por lo que los documentos muy grandes necesitan streaming u otra herramienta. El manual indica que el manejo de números de jq ha cambiado con el tiempo y depende de las opciones de compilación, y que el análisis puede perder precisión en números muy grandes o muy precisos; conviene consultar el manual de la versión instalada antes de confiar en jq para operaciones aritméticas sobre esos valores. No se reivindica ninguna medición de tiempos.