Does this rename every occurrence, or just the first one?

Every occurrence. The document is walked recursively, and every mapping that has a key with the old name gets that key renamed, regardless of how deeply nested it is or how many times the name recurs.

What happens to the key's value and its position in the document?

Both are preserved. The value under the old key becomes the value under the new key unchanged, and the renamed key keeps its original position in the mapping's key order rather than being moved to the end.

What if a mapping already has both the old and new key names?

The old key is left untouched at that specific spot rather than overwriting the existing new-name entry, since silently discarding one of two same-named values would lose data. This only applies to that one mapping; the rename still happens everywhere else the old key appears alone.

Can I use this to rename a key in only part of the document?

Not directly, the replacement always applies document-wide. If you only want part of a document changed, extract that section first (for example with a text editor or YAML Editor), run the replacer on just that snippet, then merge it back.

Does this tool send my YAML anywhere?

No, the rename happens entirely client-side using the same `yaml` parser used across this category. Nothing you paste is uploaded.

Rename YAML Keys - Replace a Mapping Key Everywhere Online

Overview

Introduction

Renaming a config field across a large YAML document by hand, especially one used at several nesting levels, is tedious and easy to get wrong: miss one occurrence and the old and new names end up inconsistently mixed. This tool renames every occurrence in one pass.

It works structurally, on the parsed document, so it can't accidentally rename a substring inside an unrelated string value the way a text-based find-and-replace could.

What Is YAML Key Replacer?

A YAML key renamer that walks a parsed document and, wherever it finds a mapping key with the old name, replaces it with the new name while keeping the associated value and the key's position in the mapping unchanged.

The result is re-serialized as clean, block-style YAML using the same writer as this category's YAML Formatter.

How YAML Key Replacer Works

The input is parsed with a full YAML 1.2 parser into a plain JS value, then rebuilt recursively: for each mapping, every key is copied to the output in its original order, except a key matching the old name is written under the new name instead, holding the same value.

If a mapping already has a key with the new name, the old-named key is left alone at that spot to avoid overwriting the existing entry; every other occurrence document-wide is still renamed normally. The rebuilt value is then re-serialized as block-style YAML.

When To Use YAML Key Replacer

Use it when migrating a config to a new schema that renamed a field, and you need every occurrence updated consistently across a large document.

It's also useful for standardizing inconsistent naming (like collapsing both `env` and `environment` into one, run it twice) across a file before validating it against a strict schema.

Often used alongside YAML Key Extractor, YAML Key Finder and YAML Value Replacer.

Features

Advantages

Renames every occurrence in one pass, eliminating the risk of missing an instance by hand.
Only touches actual mapping keys, never a matching substring inside an unrelated string value.
Preserves both the value and the key's original position in the document.
Runs entirely client-side, so configuration data never leaves your browser.

Limitations

The rename applies to the whole document; there's no way to scope it to a single section within the tool itself.
Re-serializing normalizes layout (flow style becomes block style, indentation is standardized), the same side effect as this category's other parse-and-reserialize tools.
If a mapping already has both the old and new key names, only the new-named entry survives at that spot; the old-named one there is left un-renamed rather than merged.

Examples

Renaming a recurring key

Input

user:
  name: Ada
  role: admin
address:
  role: primary

Output

user:
  name: Ada
  kind: admin
address:
  kind: primary

Every mapping with a `role` key gets it renamed to `kind`, keeping each value and position.

Best Practices & Notes

Best Practices

Search with YAML Key Finder first to confirm exactly how many places the key appears before renaming, so the result isn't a surprise.
Diff the output against the original with YAML Diff to confirm only the intended key names changed.
Run the formatter afterward if you need a specific indent width, since re-serialization uses this category's standard default.

Developer Notes

The renamer rebuilds each mapping via `Object.entries` in original iteration order (which reflects the document's key order for a parser that preserves insertion order), substituting the key name at construction time rather than mutating and reordering afterward, which is what keeps the renamed key's position stable.

YAML Key Replacer Use Cases

Migrating a YAML config to a new schema that renamed one or more fields
Standardizing inconsistent key naming across a large configuration file
Bulk-renaming a field across many nested sections of a Kubernetes manifest or CI config
Preparing a document to match a downstream tool's expected field names

Common Mistakes

Expecting a partial, scoped rename; the tool always renames the key everywhere it appears in the document.
Assuming original formatting (flow style, exact indentation) survives untouched, it doesn't, since the document is re-serialized.
Forgetting that if both old and new key names coexist in one mapping, the old one there is left as-is rather than merged.

Tips

Use YAML Key Finder beforehand to preview exactly where the rename will apply.
Chain into YAML Diff afterward to visually confirm the change matches your expectations.
For a document-wide value change instead of a key rename, use YAML Value Replacer.

YAML Key Replacer