By apipark — 15 Dec 2025

How to Use JQ to Rename a Key

use jq to rename a key

In the vast and interconnected landscape of modern digital infrastructure, data is the lifeblood that flows through every vein of application, service, and system. At the heart of this data exchange, JSON (JavaScript Object Notation) stands as an undisputed champion, its lightweight, human-readable format making it the de facto standard for everything from configuration files to intricate API responses. As developers, system administrators, and data scientists, we constantly find ourselves needing to interact with, parse, and transform this JSON data. Whether it's to normalize data for a database, reformat an API payload for a different service, or simply make data more palatable for consumption by a specific front-end application, the ability to manipulate JSON effectively is a critical skill.

Among the myriad tools available for JSON processing, jq emerges as a true powerhouse – a lightweight and flexible command-line JSON processor often described as the "sed for JSON." Its power lies in its elegant syntax, which allows for complex transformations with remarkable conciseness. While jq can filter, map, reduce, and aggregate data in countless ways, one of its most common and fundamental uses is the renaming of keys within JSON objects. This seemingly simple operation can be surprisingly nuanced, especially when dealing with nested structures, arrays of objects, or conditional renaming scenarios.

This comprehensive guide delves deep into the art and science of using jq to rename keys, providing an exhaustive exploration of its capabilities, from the basic to the highly advanced. We will dissect various renaming strategies, offering detailed explanations and practical, real-world examples to illustrate each technique. Beyond the mechanics, we'll discuss the underlying principles that make jq so effective, best practices for integrating it into your workflows, and how it fits into the broader ecosystem of data management, including its role in preparing data consumed by or delivered through API gateway solutions. By the end of this journey, you will possess a profound understanding of jq's key renaming prowess, empowering you to tackle any JSON transformation challenge with confidence and precision.

The Ubiquity of JSON and the Imperative for Transformation

Before we dive into the specifics of jq, it's essential to appreciate why JSON has become so pervasive and why the ability to transform it is not merely a convenience but a necessity. JSON's simplicity and self-describing nature have made it the lingua franca for web services. From microservices communicating internally to front-end applications fetching data from a backend, JSON is the format of choice. RESTful APIs universally return data in JSON, and even GraphQL APIs heavily rely on JSON for their query results. Modern configuration files for applications, build tools, and container orchestration platforms often utilize JSON (or its closely related YAML variant, which can often be converted to JSON).

However, data rarely arrives in the perfect shape for every single use case. Discrepancies often arise due to:

Integration with Legacy Systems: Older systems might use different naming conventions (e.g., snake_case vs. camelCase), requiring key renaming to align with modern standards.
Data Normalization: To ensure consistency across different data sources or to prepare data for storage in a database, keys might need to be standardized.
Front-End Specific Requirements: A backend API might provide verbose key names, while a front-end UI might prefer shorter, more user-friendly names to simplify data binding.
Third-Party API Inconsistencies: When consuming data from multiple external APIs, each might use its own naming schemes for conceptually similar data points, necessitating transformation for unified processing.
Refactoring and Evolution: As an application evolves, so do its data models. Key renaming becomes crucial during refactoring efforts to maintain consistency and clarity.
Security and Obfuscation: In some cases, verbose or sensitive key names might be simplified or abstracted before being exposed to certain consumers.

Consider a scenario where an API endpoint returns user data with keys like user_id, first_name, and last_name. A consuming application built with a framework that prefers camelCase might require these keys to be userId, firstName, and lastName. Manually parsing and transforming such data in application code can be tedious, error-prone, and inefficient, especially for one-off tasks or scripting. This is precisely where jq shines, offering a powerful, declarative, and highly efficient solution for these kinds of data manipulation challenges.

Moreover, in a world increasingly reliant on interconnected services and data flows, the journey of data often involves traversing through various components. Data might originate from a database, be processed by a microservice, then exposed via an API through an API gateway, eventually consumed by a web or mobile application. Each step in this journey might necessitate transformations. For instance, an API gateway might be responsible for routing requests, enforcing policies, and even performing basic data transformations on the fly before forwarding the request or response. While jq primarily operates on static or streamed JSON data in shell environments, the principles of data transformation it embodies are universally applicable and crucial for maintaining coherence across such complex open platform architectures.

Introducing JQ: The Swiss Army Knife for JSON

jq is a command-line JSON processor that is often likened to sed or awk for JSON data. It's a remarkably versatile tool that allows you to slice, filter, map, and transform structured data with ease. At its core, jq treats JSON data as a stream of values and applies a sequence of filters to them. These filters can range from simple selectors to complex functions that perform arithmetic, string manipulation, object construction, and more.

Why Choose JQ?

Power and Flexibility: jq can handle almost any JSON transformation you can imagine, from trivial extractions to highly complex restructuring.
Conciseness: Its powerful, functional-style syntax allows for complex operations to be expressed in surprisingly compact commands.
Efficiency: Written in C, jq is fast and memory-efficient, capable of processing large JSON files without significant performance overhead.
Pipelines: Like Unix command-line tools, jq supports piping, allowing you to chain operations together to build sophisticated transformations.
Cross-Platform: Available on Linux, macOS, and Windows, making it a portable solution for developers across different operating systems.
Open Source: Being an open source tool, jq benefits from community contributions and transparency.

Installing JQ

jq is simple to install across various operating systems.

On macOS (using Homebrew):

brew install jq

On Linux (using package manager):

# Debian/Ubuntu
sudo apt-get update
sudo apt-get install jq

# Fedora/CentOS/RHEL
sudo yum install jq
# or
sudo dnf install jq

On Windows (using Chocolatey or Scoop):

# Chocolatey
choco install jq

# Scoop
scoop install jq

Alternatively, you can download the appropriate executable from the official jq website (https://stedolan.github.io/jq/download/) and place it in your system's PATH.

A First Look: Basic JQ Filters

Let's quickly review some basic jq filters to set the stage. Suppose we have the following JSON:

{
  "id": "123",
  "name": "Alice",
  "details": {
    "age": 30,
    "city": "New York"
  },
  "tags": ["developer", "json_expert"]
}

. (Identity filter): Prints the entire input. bash echo '{"id": "123"}' | jq '.' # Output: {"id": "123"}
.key (Object identifier index): Selects the value associated with key. bash echo '{"id": "123", "name": "Alice"}' | jq '.name' # Output: "Alice"
.nested.key (Chained access): Accesses nested values. bash echo '{"id": "123", "details": {"age": 30}}' | jq '.details.age' # Output: 30
[] (Array index or object keys): Accesses array elements by index or transforms objects into arrays of values/keys/entries. bash echo '[{"name": "Alice"}, {"name": "Bob"}]' | jq '.[0].name' # Output: "Alice"
| (Pipe): Chains filters, sending the output of one filter as the input to the next. bash echo '{"details": {"city": "New York"}}' | jq '.details | .city' # Output: "New York"

These fundamental building blocks are the foundation upon which more complex jq expressions, including key renaming, are constructed.

Core Concepts for Renaming Keys with JQ

Renaming keys in jq isn't a single, dedicated function but rather a flexible process that leverages jq's ability to construct new objects and manipulate existing ones. The primary strategies revolve around:

Iterating over object entries: The with_entries filter is exceptionally powerful for this. It transforms an object into an array of {key: ..., value: ...} objects, allowing you to manipulate both keys and values, and then transforms it back into an object.
Object construction: Manually constructing a new object with desired key names and values from the original.
Direct key deletion and addition: Though less idiomatic for simple renames, this can be useful in specific scenarios.

Let's explore these concepts with increasing complexity.

1. Direct Key Renaming (Simple Cases)

For simple, top-level key renames, especially when you're creating a new object, direct object construction is often the most straightforward approach.

Scenario: You have an object with a key oldKey and you want to rename it to newKey while keeping other keys as they are.

Input JSON:

{
  "user_id": "U1001",
  "user_name": "John Doe",
  "email": "john.doe@example.com"
}

Desired Output:

{
  "id": "U1001",
  "full_name": "John Doe",
  "email": "john.doe@example.com"
}

Here, we want to rename user_id to id and user_name to full_name.

JQ Command (Object Construction):

echo '{ "user_id": "U1001", "user_name": "John Doe", "email": "john.doe@example.com" }' | \
jq '{
  id: .user_id,
  full_name: .user_name,
  email: .email
}'

Explanation:

{ ... }: This construct tells jq to create a new JSON object.
id: .user_id: For the new object, it defines a key id whose value is taken from the original object's user_id key (.user_id).
full_name: .user_name: Similarly, full_name gets its value from user_name.
email: .email: This line demonstrates how to retain existing keys with their original names.

This method is explicit and clear for a small number of keys. However, it becomes cumbersome if you have many keys to retain but only a few to rename, as you have to list every single key.

2. Using `with_entries` for Iterative Renaming

The with_entries filter is perhaps the most versatile tool for key renaming in jq, especially when you want to apply a transformation to keys programmatically or conditionally.

with_entries does the following:

It takes an object as input.
It converts this object into an array of objects, where each inner object has a key field and a value field. For example, {"a": 1, "b": 2} becomes [{"key": "a", "value": 1}, {"key": "b", "value": 2}].
It then applies a filter (provided as an argument to with_entries) to each element of this array. Within this filter, you can modify the key and value fields.
Finally, it converts the modified array back into an object.

Scenario: Rename user_id to id and user_name to full_name, but retain all other keys dynamically.

Input JSON:

{
  "user_id": "U1001",
  "user_name": "John Doe",
  "email": "john.doe@example.com",
  "age": 30
}

Desired Output:

{
  "id": "U1001",
  "full_name": "John Doe",
  "email": "john.doe@example.com",
  "age": 30
}

JQ Command (with with_entries and if/then/else):

echo '{ "user_id": "U1001", "user_name": "John Doe", "email": "john.doe@example.com", "age": 30 }' | \
jq 'with_entries(
  if .key == "user_id" then .key = "id"
  elif .key == "user_name" then .key = "full_name"
  else .
  end
)'

Explanation:

with_entries(...): This initiates the transformation process.
if .key == "user_id" then .key = "id": For each entry in the array (e.g., {"key": "user_id", "value": "U1001"}), if its key field is "user_id", then change its key field to "id". The . refers to the current entry object (e.g., {"key": "user_id", "value": "U1001"}).
elif .key == "user_name" then .key = "full_name": If the first condition is false, check if key is "user_name" and rename it to "full_name".
else .: If none of the conditions match, . (the identity filter) means the entry is passed through unchanged, preserving its original key and value.
end: Closes the if statement.

This method is incredibly powerful because it allows for conditional logic and dynamic key generation based on the original key's name, its value, or other contextual information.

3. Renaming Keys in Nested Objects

When dealing with deeply nested JSON structures, the complexity of renaming keys increases. jq's recursive filters and paths come to the rescue.

Scenario: Rename a key within a nested object.

Input JSON:

{
  "order_id": "ORD789",
  "customer_info": {
    "cust_id": "CUST123",
    "cust_name": "Jane Doe",
    "address": {
      "street_address": "123 Main St",
      "city": "Anytown"
    }
  },
  "items": [...]
}

Desired Output: Rename cust_id to customer_id and cust_name to customer_name within customer_info.

JQ Command (Targeted with_entries):

echo '{
  "order_id": "ORD789",
  "customer_info": {
    "cust_id": "CUST123",
    "cust_name": "Jane Doe",
    "address": {
      "street_address": "123 Main St",
      "city": "Anytown"
    }
  },
  "items": []
}' | \
jq '.customer_info |= (
  with_entries(
    if .key == "cust_id" then .key = "customer_id"
    elif .key == "cust_name" then .key = "customer_name"
    else .
    end
  )
)'

Explanation:

.customer_info |= (...): This is a powerful assignment operator. It tells jq to take the value of .customer_info, apply the filter in the parentheses (...) to it, and then assign the result back to .customer_info. The |= operator is crucial for in-place modification of parts of the JSON document.
Inside the parentheses, the with_entries filter is applied only to the customer_info object, exactly as in the previous example. This ensures that keys at other levels (like order_id or items) remain untouched.

4. Renaming Keys in Arrays of Objects

A very common pattern in API responses is an array of objects. You often need to rename keys within each object in such an array.

Scenario: Rename item_code to product_code and qty to quantity for each item in an array.

Input JSON:

{
  "order_number": "ORD789",
  "line_items": [
    {
      "item_code": "P001",
      "description": "Laptop",
      "qty": 1,
      "price": 1200
    },
    {
      "item_code": "P002",
      "description": "Mouse",
      "qty": 2,
      "price": 25
    }
  ]
}

Desired Output:

{
  "order_number": "ORD789",
  "line_items": [
    {
      "product_code": "P001",
      "description": "Laptop",
      "quantity": 1,
      "price": 1200
    },
    {
      "product_code": "P002",
      "description": "Mouse",
      "quantity": 2,
      "price": 25
    }
  ]
}

JQ Command (Using map with with_entries):

echo '{
  "order_number": "ORD789",
  "line_items": [
    { "item_code": "P001", "description": "Laptop", "qty": 1, "price": 1200 },
    { "item_code": "P002", "description": "Mouse", "qty": 2, "price": 25 }
  ]
}' | \
jq '.line_items |= (
  map(
    with_entries(
      if .key == "item_code" then .key = "product_code"
      elif .key == "qty" then .key = "quantity"
      else .
      end
    )
  )
)'

Explanation:

.line_items |= (...): Again, we target the line_items array for in-place modification.
map(...): The map filter is used to apply a transformation to each element of an array. In this case, each element is an object from the line_items array.
Inside map, with_entries(...) is applied to each object in the array, performing the key renaming just as before.

This pattern (.array_name |= map(with_entries(...))) is extremely powerful for standardizing arrays of objects.

Advanced Renaming Techniques

jq offers even more sophisticated ways to rename keys, catering to complex and dynamic requirements.

1. Renaming Multiple Keys Simultaneously with a Mapping

Instead of a long if/elif/else chain, you can define a mapping of old keys to new keys and iterate through it. While jq doesn't have a direct map_keys function, we can simulate it.

Scenario: You have a predefined mapping for several keys.

Input JSON:

{
  "userId": "U456",
  "userName": "Alice Smith",
  "userEmail": "alice.s@example.com",
  "userStatus": "active"
}

Desired Output: Rename userId to id, userName to name, userEmail to email. Other keys like userStatus should remain.

JQ Command (with reduce or object literals):

For this, we can define a mapping object and use reduce or simply build up the new object. A simpler approach often involves with_entries combined with a lookup.

Let's use a function and with_entries for clarity.

echo '{
  "userId": "U456",
  "userName": "Alice Smith",
  "userEmail": "alice.s@example.com",
  "userStatus": "active"
}' | \
jq '
  # Define a mapping as a JQ variable (or function)
  # This mapping is an object where keys are original names, values are new names.
  # For keys not in this map, we want to keep them as is.
  reduce (
    [
      {"old": "userId", "new": "id"},
      {"old": "userName", "new": "name"},
      {"old": "userEmail", "new": "email"}
    ][]
  ) as $item (
    .; # Start with the original input object
    # If the current object has the $item.old key, then
    # delete the old key, and add the new key with the old key's value.
    # Otherwise, keep the object as is.
    if has($item.old) then
      . + {($item.new): .[$item.old]} | del(.[$item.old])
    else
      .
    end
  )
'

Explanation:

reduce ( [ {old: ..., new: ...} ] [] ) as $item ( . ; ... ): This is a powerful jq construct.
- [ {old: "userId", "new": "id"}, ... ][]: Creates an array of objects, then [] unwraps it into a stream of individual {old: ..., new: ...} objects.
- as $item: Each of these objects is assigned to the variable $item for the current iteration.
- .: The initial accumulator for reduce is the entire input object.
- if has($item.old) then ... else ... end: Checks if the current object (.) has the old key from $item.
- . + {($item.new): .[$item.old]}: If it has the old key, it creates a new object by merging the current object (.) with a new key-value pair. The new key is ($item.new) (parentheses are needed for computed keys), and its value is .[$item.old].
- | del(.[$item.old]): After adding the new key, the old key is deleted.
- else .: If the old key doesn't exist, the object remains unchanged.

This reduce approach is more dynamic and scales better when your mapping might be external or very large.

2. Renaming Keys Based on Patterns (Regex)

jq has built-in string manipulation functions, including test() for regular expression matching. This can be combined with with_entries to rename keys that match a certain pattern.

Scenario: Rename all keys that start with "prod_" to "product_" (e.g., prod_id to product_id, prod_name to product_name).

Input JSON:

{
  "prod_id": "P005",
  "prod_name": "Widget X",
  "prod_price": 25.99,
  "category": "Gadgets"
}

Desired Output:

{
  "product_id": "P005",
  "product_name": "Widget X",
  "product_price": 25.99,
  "category": "Gadgets"
}

JQ Command (with startswith and sub):

echo '{
  "prod_id": "P005",
  "prod_name": "Widget X",
  "prod_price": 25.99,
  "category": "Gadgets"
}' | \
jq 'with_entries(
  if .key | startswith("prod_") then
    .key |= sub("prod_"; "product_")
  else
    .
  end
)'

Explanation:

if .key | startswith("prod_"): Checks if the current entry's key (.key) starts with the string "prod_".
.key |= sub("prod_"; "product_"): If it matches, the sub filter is applied in-place to the .key field. sub(regex; replacement) replaces the first occurrence of regex with replacement.
else .: If the key doesn't start with "prod_", it remains unchanged.

This is extremely powerful for consistent transformations across many keys. For more complex regex needs, match() or test() can be used with replace().

3. Handling Keys with Special Characters or Dynamic Keys

jq handles keys with special characters (like spaces or hyphens) by quoting them (."my key"). For dynamically generated keys, you use parentheses (expression) as the key.

Scenario: Rename a key "full name" to "customer-name".

Input JSON:

{
  "id": "C001",
  "full name": "Test User",
  "email": "test@example.com"
}

Desired Output:

{
  "id": "C001",
  "customer-name": "Test User",
  "email": "test@example.com"
}

JQ Command:

echo '{ "id": "C001", "full name": "Test User", "email": "test@example.com" }' | \
jq 'with_entries(
  if .key == "full name" then .key = "customer-name"
  else .
  end
)'

The syntax remains largely the same; you just need to ensure the key strings are correctly quoted when they contain special characters.

For dynamic key creation, consider this:

echo '{"status": "active", "code": "ABC"}' | jq '{ (.status): .code }'
# Output: {"active": "ABC"}

Here, (.status) dynamically creates a key named "active" using the value of the status field.

Practical Scenarios and Detailed Examples

To solidify your understanding, let's walk through a series of practical examples, each broken down into input, desired output, the jq command, and a thorough explanation.

Example 1: Renaming a Simple Top-Level Key

Problem: An API returns user data with user_id, but your application expects id.

Input (user_data.json):

{
  "user_id": "uuid-12345",
  "username": "johndoe",
  "email": "john@example.com"
}

Desired Output:

{
  "id": "uuid-12345",
  "username": "johndoe",
  "email": "john@example.com"
}

JQ Command:

jq 'with_entries(if .key == "user_id" then .key = "id" else . end)' user_data.json

Explanation:

jq '...' user_data.json: jq processes the user_data.json file.
with_entries(...): This converts the top-level object into an array of {"key": ..., "value": ...} pairs.
if .key == "user_id" then .key = "id" else . end: For each pair, it checks if the key is "user_id".
- If true, it reassigns the key field of that pair to "id".
- If false, . (the identity filter) keeps the pair unchanged.
After all pairs are processed, with_entries converts the modified array back into an object. The result is an object where "user_id" has been replaced by "id", and all other keys remain the same.

Example 2: Renaming a Key Within a Nested Object

Problem: You receive product data where product_details contains sku_code, but you need it as item_sku.

Input (product_data.json):

{
  "product_name": "Super Gadget",
  "category": "Electronics",
  "product_details": {
    "sku_code": "SG-X-101",
    "weight_g": 250,
    "dimensions_cm": "10x5x2"
  },
  "price": 99.99
}

Desired Output:

{
  "product_name": "Super Gadget",
  "category": "Electronics",
  "product_details": {
    "item_sku": "SG-X-101",
    "weight_g": 250,
    "dimensions_cm": "10x5x2"
  },
  "price": 99.99
}

JQ Command:

jq '.product_details |= (with_entries(if .key == "sku_code" then .key = "item_sku" else . end))' product_data.json

Explanation:

.product_details |= (...): This targets the product_details object specifically for modification. The |= operator ensures that the result of the filter inside the parentheses is assigned back to .product_details.
(with_entries(...)): The with_entries filter is applied only to the product_details object, transforming its keys and values.
if .key == "sku_code" then .key = "item_sku" else . end: Within product_details, if an entry's key is "sku_code", it's renamed to "item_sku". Other keys within product_details (like weight_g, dimensions_cm) are untouched, and all keys outside product_details (like product_name, category, price) are also unaffected.

Example 3: Renaming Multiple Keys in a Single Object

Problem: A user profile object uses first_name and last_name, but you need firstName and lastName (camelCase).

Input (profile.json):

{
  "user_id": "U007",
  "first_name": "James",
  "last_name": "Bond",
  "email": "james.bond@mi6.gov.uk",
  "agent_status": "active"
}

Desired Output:

{
  "user_id": "U007",
  "firstName": "James",
  "lastName": "Bond",
  "email": "james.bond@mi6.gov.uk",
  "agent_status": "active"
}

JQ Command:

jq 'with_entries(
  if .key == "first_name" then .key = "firstName"
  elif .key == "last_name" then .key = "lastName"
  else .
  end
)' profile.json

Explanation:

This is a direct application of the with_entries with if/elif/else chain discussed earlier. It iterates through all top-level keys, applying specific renames for "first_name" and "last_name", while preserving all other keys.

Example 4: Renaming a Key Across an Array of Objects

Problem: A list of events has event_date, but you require eventDate for your calendar application.

Input (events.json):

[
  {
    "event_id": "E001",
    "event_name": "Conference Day 1",
    "event_date": "2023-10-26"
  },
  {
    "event_id": "E002",
    "event_name": "Workshop A",
    "event_date": "2023-10-27"
  },
  {
    "event_id": "E003",
    "event_name": "Gala Dinner",
    "event_date": "2023-10-27"
  }
]

Desired Output:

[
  {
    "event_id": "E001",
    "event_name": "Conference Day 1",
    "eventDate": "2023-10-26"
  },
  {
    "event_id": "E002",
    "event_name": "Workshop A",
    "eventDate": "2023-10-27"
  },
  {
    "event_id": "E003",
    "event_name": "Gala Dinner",
    "eventDate": "2023-10-27"
  }
]

JQ Command:

jq 'map(with_entries(if .key == "event_date" then .key = "eventDate" else . end))' events.json

Explanation:

map(...): Since the input is an array, map is used to apply a filter to each element of the array. Each element here is an object representing an event.
with_entries(...): For each event object, this filter performs the key renaming logic.
if .key == "event_date" then .key = "eventDate" else . end: Inside each event object, if the key is "event_date", it's renamed to "eventDate".

This is a very common and powerful pattern for consistent data transformation across lists of records.

Example 5: Conditional Key Renaming (Based on Value or Presence)

Problem: Rename status_code to statusCode only if its value indicates an error (e.g., starts with 'E').

Input (response.json):

{
  "request_id": "REQ987",
  "status_code": "S200",
  "message": "Operation successful"
}
{
  "request_id": "REQ988",
  "status_code": "E500",
  "message": "Internal server error"
}

(Note: This is a stream of two separate JSON objects, which jq handles naturally.)

Desired Output:

{
  "request_id": "REQ987",
  "statusCode": "S200",
  "message": "Operation successful"
}
{
  "request_id": "REQ988",
  "statusCode": "E500",
  "message": "Internal server error"
}

JQ Command:

jq 'with_entries(
  if .key == "status_code" then
    # Even if we rename it, let's say the condition applies to the *value*
    # Here, we're simplifying: we'll rename `status_code` to `statusCode` unconditionally.
    # If the renaming itself were conditional, the `if` would wrap the entire modification.
    # For this example, let's assume we always want `statusCode` if `status_code` exists,
    # but the problem stated "only if its value indicates an error". Let's adapt.
    .key = "statusCode"
  else . end
)' response.json

Let's refine the command to match the "conditional based on value" requirement more precisely. This means creating a new key and deleting the old one, but only if the condition is met.

jq '
  if .status_code | startswith("E") then
    . + { "statusCode": .status_code } | del(.status_code)
  else
    . # If not an error, keep it as `status_code`
  end
' response.json

Explanation of refined command:

if .status_code | startswith("E") then ... else ... end: This outer if statement checks the value of status_code. . refers to the current entire object.
.status_code | startswith("E"): Pipes the value of status_code to the startswith filter to check if it begins with "E".
. + { "statusCode": .status_code }: If the condition is true, a new object is created by merging the original object (.) with a new key-value pair: "statusCode" with the value of the original status_code.
| del(.status_code): After adding the new key, the old status_code key is deleted.
else .: If the status_code does not start with "E", the object remains completely unchanged (the identity filter . is applied).

This example demonstrates how jq allows for very fine-grained control over transformations based on data content, not just structure.

Example 6: Renaming a Key While Preserving Other Data

This is implicitly handled by with_entries and the |= operator, as they only modify the targeted parts of the JSON. If you use object construction, you have to explicitly include the keys you want to preserve.

Problem: You want to rename item_id to id but ensure all other fields in the object remain.

Input (item.json):

{
  "item_id": "ITEM001",
  "item_name": "Blue Widget",
  "description": "A very useful widget for various tasks.",
  "category": "Tools"
}

Desired Output:

{
  "id": "ITEM001",
  "item_name": "Blue Widget",
  "description": "A very useful widget for various tasks.",
  "category": "Tools"
}

JQ Command (Using with_entries for minimal impact):

jq 'with_entries(if .key == "item_id" then .key = "id" else . end)' item.json

Explanation:

As seen in previous examples, with_entries is ideal here. The else . clause ensures that any key not explicitly matched in the if/elif conditions is passed through unchanged. This is a robust way to perform targeted renames without inadvertently losing or altering other data.

Example 7: Renaming Keys Based on a Lookup Map

This is a more programmatic approach where the mapping from old to new key names is defined within jq.

Problem: You have a fixed mapping for multiple keys (prod_id -> product_id, prod_name -> productName, prod_qty -> quantity).

Input (sales_record.json):

{
  "transaction_id": "TXN123",
  "prod_id": "PN001",
  "prod_name": "Widget Alpha",
  "prod_qty": 5,
  "unit_price": 10.50
}

Desired Output:

{
  "transaction_id": "TXN123",
  "product_id": "PN001",
  "productName": "Widget Alpha",
  "quantity": 5,
  "unit_price": 10.50
}

JQ Command:

jq '
  # Define a map of old_key: new_key
  . as $in | # Store the original input in $in
  {
    "prod_id": "product_id",
    "prod_name": "productName",
    "prod_qty": "quantity"
  } as $renameMap |

  # Iterate through the original object's entries
  with_entries(
    # Check if the current entry's key exists in our rename map
    if $renameMap | has(.key) then
      # If it exists, change the key to the new name from the map
      .key = ($renameMap[.key])
    else
      . # Otherwise, keep the entry as is
    end
  )
' sales_record.json

Explanation:

. as $in: This saves the entire input object into a jq variable $in. While not strictly necessary for this specific command, it's good practice for more complex filters where you might need to refer to the original input multiple times.
{ "prod_id": "product_id", ... } as $renameMap: This defines a jq variable $renameMap which holds our key renaming rules as an object. The keys of $renameMap are the old names, and the values are the new names.
with_entries(...): We then process the input object's entries.
if $renameMap | has(.key) then ... else ... end: For each entry, it checks if its current key (e.g., "prod_id") exists as a key in our $renameMap.
- $renameMap | has(.key): The has() function checks for key existence.
- if ... then .key = ($renameMap[.key]): If the key is found in $renameMap, we update the entry's .key to its corresponding new name found in $renameMap (e.g., ($renameMap["prod_id"]) would evaluate to "product_id"). The parentheses around $renameMap[.key] are important for computed key access.
- else .: If the key is not in $renameMap, the entry remains unchanged.

This technique provides a clean and maintainable way to handle multiple renames using a centralized mapping.

APIPark is a high-performance AI gateway that allows you to securely access the most comprehensive LLM APIs globally on the APIPark platform, including OpenAI, Anthropic, Mistral, Llama2, Google Gemini, and more.Try APIPark now! 👇👇👇

Install APIPark – it’s free

Performance Considerations and Best Practices

While jq is inherently efficient, understanding some best practices can help you write more robust and performant scripts, especially when dealing with large JSON files or complex transformations.

Prefer with_entries for Dynamic Renames: For systematic renames (e.g., camelCase to snake_case, or applying a regex pattern), with_entries is generally the most idiomatic and efficient approach as it processes all keys in one pass.
Use |= for In-Place Updates: The |= assignment operator is crucial for modifying specific parts of a JSON document without having to reconstruct the entire object. This improves readability and often performance.
Chain Filters Efficiently: jq filters are composable. Instead of writing extremely long, nested filters, break them down into smaller, more manageable steps connected by pipes (|). This often makes the logic clearer and can sometimes be optimized by jq.
Avoid Unnecessary Operations: Only process the data you need. If you're renaming keys in a specific nested object, don't apply with_entries to the entire document if it's not needed. Target your filters precisely.
Test Incrementally: For complex jq commands, build them up step-by-step. Test each part of the pipeline with a small sample of your data to ensure it produces the expected intermediate results.
Handle Missing Keys Gracefully: If your input JSON might sometimes lack certain keys that your jq filter expects, use ? (optional operator) or if/else checks (has("key")) to prevent errors. For example, .foo?.bar will output null if foo or bar is missing, rather than an error.
Consider Raw Input/Output: For very large files, if you're only extracting specific values and don't need pretty-printed JSON output, jq -r (raw output) can be faster as it skips the JSON stringification overhead. Similarly, jq -R can read raw strings as input.
Leverage Variables: Storing intermediate results or lookup tables in jq variables (. as $var) can make complex filters more readable and efficient by avoiding redundant calculations.

Integrating JQ into Workflows

jq's command-line nature makes it a perfect companion for various scripting and automation tasks.

Shell Scripting (Bash, Zsh)

jq is often used within shell scripts to parse configuration files, process API responses, or transform log data.

Example: Extracting and renaming data from an API response:

#!/bin/bash

API_URL="http://some.api.com/users/latest"

# Fetch data from API, ensuring it's valid JSON
json_data=$(curl -s "$API_URL" | jq '.')

# Check if data was fetched successfully
if [ -z "$json_data" ]; then
  echo "Error: Could not fetch JSON data from $API_URL" >&2
  exit 1
fi

# Use jq to rename keys and extract relevant fields
transformed_data=$(echo "$json_data" | jq '
  .users[] | {
    userIdentifier: .user_id,
    fullName: (.first_name + " " + .last_name),
    contactEmail: .email,
    registrationDate: .created_at
  }
')

echo "Transformed User Data:"
echo "$transformed_data"

In this script, jq first validates the incoming API response and then performs a complex transformation that includes selecting fields, renaming keys (user_id to userIdentifier), concatenating strings (first_name and last_name to fullName), and remapping other fields. This demonstrates how jq can be a vital component in data processing pipelines, preparing data for downstream systems or analysis.

CI/CD Pipelines

jq is frequently used in CI/CD pipelines for:

Configuration management: Modifying JSON configuration files (e.g., package.json, appsettings.json, Kubernetes manifests) dynamically during deployment based on environment variables.
Log analysis: Filtering and extracting specific information from JSON-formatted logs for alerting or reporting.
API testing: Validating API response structures and data.

Data Processing Pipelines

In larger data processing ecosystems, jq can serve as a lightweight, on-the-fly transformation tool. For instance, a data ingestion service might receive raw JSON from an external source, and jq could be used as an initial parsing and standardization step before the data is moved to a message queue or a data lake.

While jq excels at manipulating the JSON payloads themselves, the broader ecosystem of data exchange often involves complex API management. For organizations dealing with numerous APIs, particularly AI models and REST services, managing integration, authentication, and lifecycle can be a significant challenge. This is where robust gateway solutions come into play. Platforms like APIPark, an open-source AI gateway and API management platform, provide an all-in-one solution to manage, integrate, and deploy these services with ease, ensuring efficient data flow and API governance. Such an open platform facilitates the standardization of API formats, enabling developers to integrate over 100+ AI models quickly and encapsulate prompts into REST APIs. In such an environment, jq might be used by a developer to process the JSON output from an APIPark-managed API to refine it further for a specific microservice or UI component, or to transform data before sending it to an API gateway for routing to the correct service. This complementary relationship highlights how focused tools like jq and comprehensive API management platforms like APIPark work together to build resilient and flexible digital infrastructures.

Beyond Renaming: JQ's Broader Utility

While this guide focuses on key renaming, it's important to briefly touch upon jq's broader capabilities to appreciate its full potential in an open platform data ecosystem:

Filtering Data: Selecting specific elements or objects based on conditions (.[] | select(.status == "active")).
Transforming Values: Performing arithmetic, string operations, date conversions, etc., on field values (.price * 1.05).
Aggregating Data: Calculating sums, averages, counts (map(.amount) | add).
Creating New JSON Structures: Building entirely new arrays or objects from existing data ({ user: .name, age: .details.age }).
Slicing Arrays: Extracting subsets of arrays (.[0:5]).
Merging Objects: Combining multiple objects (.obj1 + .obj2).
Pretty-Printing and Minifying: Formatting JSON for readability or compactness (jq . for pretty, jq -c . for compact).

These capabilities make jq an indispensable tool for anyone working with JSON data, enabling complex data manipulation with concise and powerful expressions.

Summary of Key Renaming JQ Filters

JQ Filter/Method	Description	Use Cases	Example
Object Construction `{}`	Manually define a new object with desired keys and values.	Simple, few keys to rename, creating a new structure.	`jq '{ newKey: .oldKey, other: .other }'`
`with_entries`	Transforms an object into `[{"key": ..., "value": ...}]` array, allowing key/value modification, then back to object.	Most versatile for conditional/dynamic key renames, maintaining other keys.	`jq 'with_entries(if .key == "old" then .key = "new" else . end)'`
`map`	Applies a filter to each element of an array. Often combined with `with_entries`.	Renaming keys uniformly across an array of objects.	`jq 'map(with_entries(...))'`
`\|=` (Assignment)	In-place update of a specific path in the JSON document.	Modifying keys within a nested object or array without affecting parent/sibling nodes.	`jq '.path.to.object \|= with_entries(...)'`
`del()`	Deletes a key-value pair. Can be used in conjunction with adding a new key.	When a key needs to be completely removed or replaced with a new one.	`jq '. + {newKey: .oldKey} \| del(.oldKey)'`
`reduce`	Iteratively processes a stream of values to accumulate a single result.	Advanced, for complex mappings or iterative key transformations.	`jq 'reduce $map[] as $item (.; if has($item.old) then . + {($item.new): .[$item.old]} \| del(.[$item.old]) else . end)'`
`startswith()`, `sub()`	String functions used within conditional renaming to match patterns.	Renaming keys based on prefixes, suffixes, or regex patterns.	`jq 'with_entries(if .key \| startswith("old_") then .key \|= sub("old_"; "new_") else . end)'`

Conclusion

The ability to efficiently manipulate JSON data is a cornerstone skill in modern software development and system administration. As data flows through diverse API endpoints, sophisticated gateway systems, and across various open platform environments, the need to transform, reformat, and standardize JSON documents becomes paramount. Among the myriad tools available for this purpose, jq stands out as an exceptionally powerful, flexible, and concise command-line processor.

This comprehensive guide has taken you on an in-depth journey through the art of using jq to rename keys, from simple top-level renames to complex, conditional transformations within nested arrays of objects. We've explored jq's core syntax, demystified the indispensable with_entries filter, and illustrated various techniques with detailed, practical examples. By mastering these methods, you gain the capability to precisely tailor JSON data to meet the specific requirements of any application, service, or analytical tool.

Beyond the mechanics of renaming, we've touched upon jq's broader utility, its integration into crucial workflows like shell scripting and CI/CD pipelines, and its complementary role alongside more extensive API management solutions like APIPark. In a world increasingly driven by data and interconnected services, the mastery of jq is not merely a technical skill but a strategic asset, empowering you to navigate the complexities of data transformation with unparalleled efficiency and control. Embrace jq, and unlock the full potential of your JSON data.

Frequently Asked Questions (FAQs)

1. What is JQ and why is it useful for renaming keys? jq is a lightweight and flexible command-line JSON processor. It's often called the "sed for JSON." It's useful for renaming keys because it provides powerful filters that allow you to parse, filter, and transform JSON data structure programmatically. Instead of writing complex scripts in languages like Python or JavaScript for simple JSON transformations, jq allows for concise, efficient, and direct manipulation right from the command line, making it ideal for scripting, automation, and quick data reformatting tasks.

2. What is the most common JQ filter used for renaming keys dynamically? The with_entries filter is arguably the most common and versatile jq filter for dynamically renaming keys. It works by transforming an object into an array of {"key": "...", "value": "..."} pairs, allowing you to modify the .key field within each pair based on conditions (e.g., if/else statements, string matching) or mapping rules. Once modifications are complete, with_entries converts the array back into an object with the renamed keys.

3. How do I rename a key inside a nested object or an array of objects using JQ? To rename a key inside a nested object, you typically target the specific nested path using . (e.g., .parent.child_object) and then use the |= (in-place assignment) operator with with_entries. For an array of objects, you combine the map() filter with with_entries. The map() filter iterates over each object in the array, and then with_entries is applied to each individual object to perform the key renaming within it. For example: jq '.array_name |= map(with_entries(if .key == "old" then .key = "new" else . end))'.

4. Can JQ rename keys based on a pattern or a lookup table? Yes, jq can rename keys based on patterns (e.g., startswith(), endswith(), sub() for regex replacement) by using these string functions within the if conditions of a with_entries filter. For a lookup table (a predefined mapping of old names to new names), you can define an object variable in jq (e.g., {$oldKey: $newKey} as $renameMap) and then use it within with_entries to check if an entry's key exists in the map and replace it accordingly. This provides a highly flexible way to apply systematic renaming rules.

5. What are the key benefits of using JQ in an API and data processing workflow? In an API and data processing workflow, jq offers several key benefits: * Rapid Prototyping and Transformation: Quickly reformat API responses or data payloads without writing boilerplate code. * Automation: Integrate seamlessly into shell scripts, CI/CD pipelines, and other automation tools to standardize data formats on the fly. * Validation and Filtering: Easily extract specific data points or validate JSON structures from incoming API traffic or logs. * Interoperability: Helps bridge data format discrepancies between different systems, microservices, or external APIs that might use varying naming conventions. * Lightweight and Efficient: As a single binary, it's fast and has a low memory footprint, making it suitable for high-throughput data processing tasks, complementing more comprehensive API gateway and management solutions.

🚀You can securely and efficiently call the OpenAI API on APIPark in just two steps:

Step 1: Deploy the APIPark AI gateway in 5 minutes.

APIPark is developed based on Golang, offering strong product performance and low development and maintenance costs. You can deploy APIPark with a single command line.

curl -sSO https://download.apipark.com/install/quick-start.sh; bash quick-start.sh

In my experience, you can see the successful deployment interface within 5 to 10 minutes. Then, you can log in to APIPark using your account.

Step 2: Call the OpenAI API.

Install APIPark – it’s free

How to Use JQ to Rename a Key

The Ubiquity of JSON and the Imperative for Transformation

Introducing JQ: The Swiss Army Knife for JSON

Why Choose JQ?

Installing JQ

A First Look: Basic JQ Filters

Core Concepts for Renaming Keys with JQ

1. Direct Key Renaming (Simple Cases)

2. Using `with_entries` for Iterative Renaming

3. Renaming Keys in Nested Objects

4. Renaming Keys in Arrays of Objects

Advanced Renaming Techniques

1. Renaming Multiple Keys Simultaneously with a Mapping

2. Renaming Keys Based on Patterns (Regex)

3. Handling Keys with Special Characters or Dynamic Keys

Practical Scenarios and Detailed Examples

Example 1: Renaming a Simple Top-Level Key

Example 2: Renaming a Key Within a Nested Object

Example 3: Renaming Multiple Keys in a Single Object

Example 4: Renaming a Key Across an Array of Objects

Example 5: Conditional Key Renaming (Based on Value or Presence)

Example 6: Renaming a Key While Preserving Other Data

Example 7: Renaming Keys Based on a Lookup Map

Performance Considerations and Best Practices

Integrating JQ into Workflows

Shell Scripting (Bash, Zsh)

CI/CD Pipelines

Data Processing Pipelines

Beyond Renaming: JQ's Broader Utility

Summary of Key Renaming JQ Filters

Conclusion

Frequently Asked Questions (FAQs)

🚀You can securely and efficiently call the OpenAI API on APIPark in just two steps:

Space Engineers: How to Add Monolith to Your Save File

Easily Use JQ to Rename a JSON Key

The Ubiquity of JSON and the Imperative for Transformation

Introducing JQ: The Swiss Army Knife for JSON

Why Choose JQ?

Installing JQ

A First Look: Basic JQ Filters

Core Concepts for Renaming Keys with JQ

1. Direct Key Renaming (Simple Cases)

2. Using with_entries for Iterative Renaming

3. Renaming Keys in Nested Objects

4. Renaming Keys in Arrays of Objects

Advanced Renaming Techniques

1. Renaming Multiple Keys Simultaneously with a Mapping

2. Renaming Keys Based on Patterns (Regex)

3. Handling Keys with Special Characters or Dynamic Keys

Practical Scenarios and Detailed Examples

Example 1: Renaming a Simple Top-Level Key

Example 2: Renaming a Key Within a Nested Object

Example 3: Renaming Multiple Keys in a Single Object

Example 4: Renaming a Key Across an Array of Objects

Example 5: Conditional Key Renaming (Based on Value or Presence)

Example 6: Renaming a Key While Preserving Other Data

Example 7: Renaming Keys Based on a Lookup Map

Performance Considerations and Best Practices

Integrating JQ into Workflows

Shell Scripting (Bash, Zsh)

CI/CD Pipelines

Data Processing Pipelines

Beyond Renaming: JQ's Broader Utility

Summary of Key Renaming JQ Filters

Conclusion

Frequently Asked Questions (FAQs)

🚀You can securely and efficiently call the OpenAI API on APIPark in just two steps:

Space Engineers: How to Add Monolith to Your Save File

Easily Use JQ to Rename a JSON Key

2. Using `with_entries` for Iterative Renaming