YAML Key Renamer

What does the YAML Key Renamer do?

The YAML Key Renamer on blueutils.com renames object and dictionary property keys across YAML configuration files, Kubernetes manifests, and cloud documents. It supports recursive deep replacement across all nested mappings and arrays, root-level scoping, and exact or case-insensitive matching while preserving values, data types, and formatting.

Core Concepts

Understanding key replacement behaviors in YAML documents:

• Recursive vs. Root Scope: Recursive renaming updates the target key in every nested dictionary and sequence of objects. Root-only scoping targets top-level properties without touching nested child objects.
• Case Matching Options: Exact matching (exact) matches the precise case of the old key, while case-insensitive matching (case-insensitive) updates keys irrespective of casing variations (camelCase, PascalCase, or snake_case).
• Data Integrity Preservation: Property values, string payloads, array ordering, numbers, and boolean types remain strictly unchanged during key transformation.

How to use the tool?

1. Paste or Upload YAML Payload: Paste your YAML configuration into the left Raw YAML Input editor, click Upload, or click Sample.
2. Specify Keys & Options: Enter the Old Key Name to replace and the New Key Name to set. Choose your Scope (All Levels or Root Only) and Case Sensitivity.
3. Instant Renaming & Export: Keys are renamed in real time as you type or change options. Click Copy to copy the renamed YAML or Download to save your updated blueutils-renamed.yaml file.

Related Developer Utilities

If you work with YAML refactoring, key manipulation, and schema migrations, explore these related tools:

• YAML Sorter: Alphabetically sort YAML keys recursively for clean Git diffs.
• YAML Formatter: Prettify and format YAML documents with custom indentation rules.
• YAML Diff Tool: Compare and inspect semantic differences between two YAML files side-by-side.
• YAML to JSON Converter: Convert YAML configuration files into standardized JSON documents.

REST API Integration

blueutils.com provides a free REST API endpoint (POST https://blueutils.com/api/yaml/rename-key) to programmatically rename property keys across YAML payloads.

API Request Parameters

API Request Payload Examples

cURL (Using Raw String)

curl -X POST https://blueutils.com/api/yaml/rename-key \
  -H "Content-Type: application/json" \
  -d '{
    "rawText": "server:\n  host: localhost\n  port: 8080\ndatabase:\n  host: db.internal",
    "oldKey": "host",
    "newKey": "hostname",
    "scope": "all"
  }'

cURL (Using Direct Object)

curl -X POST https://blueutils.com/api/yaml/rename-key \
  -H "Content-Type: application/json" \
  -d '{
    "yaml": {
      "server": { "host": "localhost", "port": 8080 }
    },
    "oldKey": "host",
    "newKey": "hostname"
  }'

Python

import requests

url = "https://blueutils.com/api/yaml/rename-key"
payload = {
    "rawText": "server:\n  host: localhost\n  port: 8080\ndatabase:\n  host: db.internal",
    "oldKey": "host",
    "newKey": "hostname",
    "scope": "all"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String jsonPayload = """
            {
                "rawText": "server:\\n  host: localhost\\n  port: 8080",
                "oldKey": "host",
                "newKey": "hostname",
                "scope": "all"
            }
            """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://blueutils.com/api/yaml/rename-key"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

API Response Parameters

API Response Payload Examples

Success Response (HTTP 200 OK)

{
  "isValid": true,
  "message": "Successfully renamed 2 key occurrences in YAML document.",
  "renamedYaml": "server:\n  hostname: localhost\n  port: 8080\ndatabase:\n  hostname: db.internal",
  "data": {
    "server": {
      "hostname": "localhost",
      "port": 8080
    },
    "database": {
      "hostname": "db.internal"
    }
  },
  "replacementsCount": 2,
  "originalSize": 54,
  "resultSize": 58
}

Validation Failure Response (HTTP 400 Bad Request)

{
  "isValid": false,
  "error": "Invalid input: Target old key name cannot be empty."
}

Rate Limit Exceeded Response (HTTP 429 Too Many Requests)

{
  "error": "API rate limit exceeded. Please wait or contact support@blueutils.com."
}

Why use an API to rename YAML keys?

Integrating the YAML key renamer API into migration scripts, schema refactoring tools, and continuous delivery pipelines provides concrete advantages:

• Automated Schema Migration: Seamlessly rename deprecated configuration properties across hundreds of microservice manifests during version upgrades.
• Config Standardization: Harmonize naming conventions (e.g. converting uri to url or dbHost to db_host) across disparate YAML deployment templates.
• Optimized Token Efficiency for AI Agents: AI assistants can rename keys across large YAML documents with a single API request instead of regenerating massive configuration bodies token-by-token.

Native Usage

How to rename YAML keys locally in terminal environments:

Windows (CMD / PowerShell)

# Rename YAML key using Python in PowerShell
python -c "
import yaml

def rename_key(obj, old_k, new_k):
    if isinstance(obj, dict):
        return { (new_k if k == old_k else k): rename_key(v, old_k, new_k) for k, v in obj.items() }
    if isinstance(obj, list):
        return [rename_key(i, old_k, new_k) for i in obj]
    return obj

data = yaml.safe_load(open('config.yaml'))
updated = rename_key(data, 'host', 'hostname')
with open('config.renamed.yaml', 'w') as f:
    yaml.dump(updated, f, default_flow_style=False)
print('Key renamed successfully.')
"

Linux / Unix (Bash)

# Rename YAML key using yq
yq '.. |= with(select(has("host")), .hostname = .host | del(.host))' config.yaml > config.renamed.yaml

Python

Using PyYAML:

import yaml

def rename_keys_deep(data, old_key, new_key):
    if isinstance(data, dict):
        return {
            (new_key if k == old_key else k): rename_keys_deep(v, old_key, new_key)
            for k, v in data.items()
        }
    elif isinstance(data, list):
        return [rename_keys_deep(item, old_key, new_key) for item in data]
    return data

with open("config.yaml", "r") as f:
    raw_data = yaml.safe_load(f)

updated_data = rename_keys_deep(raw_data, "host", "hostname")
with open("config.renamed.yaml", "w") as f:
    yaml.dump(updated_data, f, default_flow_style=False)

print("Key renamed successfully.")

Java

Using Jackson with YAMLMapper:

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.node.ObjectNode;
import com.fasterxml.jackson.dataformat.yaml.YAMLMapper;
import java.io.File;
import java.util.Iterator;
import java.util.Map;

public class YamlKeyRenamerExample {
    public static void renameKey(JsonNode node, String oldKey, String newKey) {
        if (node.isObject()) {
            ObjectNode obj = (ObjectNode) node;
            if (obj.has(oldKey)) {
                JsonNode value = obj.get(oldKey);
                obj.remove(oldKey);
                obj.set(newKey, value);
            }
            Iterator<JsonNode> elements = obj.elements();
            while (elements.hasNext()) {
                renameKey(elements.next(), oldKey, newKey);
            }
        } else if (node.isArray()) {
            for (JsonNode child : node) {
                renameKey(child, oldKey, newKey);
            }
        }
    }

    public static void main(String[] args) throws Exception {
        YAMLMapper mapper = new YAMLMapper();
        JsonNode root = mapper.readTree(new File("config.yaml"));
        renameKey(root, "host", "hostname");
        mapper.writeValue(new File("config.renamed.yaml"), root);

        System.out.println("YAML key renamed successfully.");
    }
}