jq Object and Array Construction
jq {key: value} builds a new object and [ exprs ] builds a new array from whatever filters you put inside.
Reshaping a verbose API response into a small object or array is the core of building a GitHub Actions matrix in CI.
What it does
Object construction {a: .x, b: .y} builds an object from filter results; {name} is shorthand for {name: .name}. Array construction [f] collects every output of f into an array. Combine them to map an API array into matrix entries.
Common usage
# reshape each item into a small object
jq 'map({name: .name, sha: .commit.sha})' tags.json
# shorthand when keys match fields
jq '.[] | {name, id}' repos.json
# collect a stream into an array
jq '[.[] | .name]' tags.jsonOperators
| Form | What it does |
|---|---|
| {k: .v} | Build an object with key k |
| {name} | Shorthand for {name: .name} |
| {(.k): .v} | Dynamic key from an expression |
| [ f ] | Collect outputs of f into an array |
In CI
Build matrix entries with map({...}) and emit with -c so the JSON is a single line for $GITHUB_OUTPUT. Use {(.key): .value} when the object key must come from data rather than a literal.
Common errors in CI
"jq: error: syntax error, unexpected \":\"" usually means a missing comma between object fields. "jq: error: Object keys must be strings" means a dynamic key (.k) evaluated to a non-string; wrap it with tostring. "jq: error: Cannot index null" means a source field path was missing.