Rename Keys

Rename item field names

Overview

The Rename Keys tool renames properties/fields in item JSON data. It supports two modes: (1) Direct key mapping with dot-notation for nested paths (e.g., level1.level2.oldKey → level1.level2.newKey), and (2) Regex-based bulk renaming with depth control, case-insensitive matching, and capture group replacement.

Category: Core Nodes
Tool Name: rename_keys
Version: 1

Appearance: Icon: lucide-Replace | Color: #772244

Node Type

Action — processes input items and produces output

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool does not require any credentials.

Parameters

Parameter	Type	Required	Default	Description
Keys	fixedCollection	No	{}	Adds a key which should be renamed. Accepts multiple entries, applied in the order you list them.
— Current Key Name	string	No	—	The current name of the key. Supports dot-notation for nested paths (e.g., “level1.level2.currentKey”).
— New Key Name	string	No	—	The new name for the key. Supports dot-notation for nested paths (e.g., “level1.level2.newKey”).
Additional Options	collection	No	{}	Bulk renaming by pattern, applied after the direct renames above.
— Regex	fixedCollection	No	{}	Adds a regular expression for bulk key renaming. Accepts multiple entries.
— — Regular Expression	string	No	—	Regex to match the key name.
— — Replace With	string	No	—	The replacement string. Supports regex captures ($1, $2, etc.).
— — Options	collection	No	{}	Matching settings for this one expression.
— — — Case Insensitive	boolean	No	false	Whether to use case insensitive match.
— — — Max Depth	number	No	-1	Maximum depth to replace keys (-1 for unlimited, 0 for top level only).
Max Concurrency	number	No	10	Maximum number of items to process concurrently.

Output Data

One output item per input item, with the same values under new names. The item is copied and rewritten, so nothing else changes: values, types and nesting are untouched, and binary data is forwarded.

Renaming runs in two passes:

1. Keys — each Current Key Name is looked up (dot-notation walks into nested objects), removed, and written back at New Key Name. An entry is skipped when either name is empty, when both names are identical, or when the field is not present on the item — a missing field is never an error.
2. Regex — every entry in Additional Options → Regex is applied to the key names themselves. A key that matches is replaced using the expression, so ^temp_(.+)$ with final_$1 turns temp_total into final_total. Matching is case-sensitive unless Case Insensitive is on, and Max Depth limits how far into nested objects the rename descends (0 = top level only, -1 = the whole item). Array indices are never renamed, but the objects inside arrays are still visited.

Because both passes rewrite key names, downstream expressions must use the new names, e.g. {{ $json.first_name }}.

Usage Examples

• Rename “firstName” to “first_name” using direct mapping
• Use regex to strip prefixes from all field names
• Rename nested fields using dot-notation paths

Example Configuration

Rename two fields:

{
  "type": "rename_keys",
  "parameters": {
    "maxConcurrency": 5,
    "keys": {
      "key": [
        {
          "currentKey": "email_address",
          "newKey": "email"
        },
        {
          "currentKey": "phone_number",
          "newKey": "phone"
        }
      ]
    }
  }
}

Rename a nested field with dot-notation:

{
  "type": "rename_keys",
  "parameters": {
    "keys": {
      "key": [
        {
          "currentKey": "user.profile.displayName",
          "newKey": "user.profile.name"
        }
      ]
    }
  }
}

Strip a prefix from every matching key, two levels deep:

{
  "type": "rename_keys",
  "parameters": {
    "additionalOptions": {
      "regexReplacement": {
        "replacements": [
          {
            "searchRegex": "^temp_(.+)$",
            "replaceRegex": "final_$1",
            "options": {
              "caseInsensitive": true,
              "depth": 2
            }
          }
        ]
      }
    }
  }
}

Combine a direct rename with a bulk pattern:

{
  "type": "rename_keys",
  "parameters": {
    "maxConcurrency": 10,
    "keys": {
      "key": [
        {
          "currentKey": "id",
          "newKey": "recordId"
        }
      ]
    },
    "additionalOptions": {
      "regexReplacement": {
        "replacements": [
          {
            "searchRegex": "^temp_(.+)$",
            "replaceRegex": "$1",
            "options": {
              "caseInsensitive": true,
              "depth": 3
            }
          }
        ]
      }
    }
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

Renames item field names using direct key mapping or regex patterns with dot-notation support.

Behavior notes

• Direct renames run before regex renames. A regex written against the original key name will not match if a Keys entry already renamed that field.
• A rename that lands on an existing key overwrites it. Check for collisions before renaming several fields onto similar names.
• Dot-notation is the default. A key that genuinely contains a dot in its name has to be reached with a regex instead, since the direct mapping treats the dot as a path separator.