jq keys_unsorted is not an ordering contract

jq has two convenient ways to inspect an object’s keys:

1
2
3
4
5

printf '%s\n' '{"b":2,"a":1}' | jq 'keys'
# ["a", "b"]

printf '%s\n' '{"b":2,"a":1}' | jq 'keys_unsorted'
# Typically ["b", "a"]

keys sorts the result. The jq manual describes keys_unsorted as returning keys roughly in insertion order. That makes it useful when inspecting a document, but it is weaker than a guarantee that every transformation will preserve an intended order.

If order matters to the application, put it in an array:

1
2
3
4

[
  {"name": "b", "value": 2},
  {"name": "a", "value": 1}
]

Now jq '.[].name' follows an explicit sequence. A consumer does not have to infer a display order from the way an object happened to be written or reconstructed.

I would use keys_unsorted for a quick look at familiar input. For a report, API contract or reproducible export, I would define the ordering directly or sort by an explicit field.

Reference: jq manual: keys and keys_unsorted.