YAML URL Encode

YAML in a query string

A pipeline parameter, a config override on a webhook, a values fragment you want to pass to a job — YAML ends up in URLs less often than JSON does, but when it does the stakes are higher, because YAML carries meaning in places JSON does not. Indentation is structure. A line break is structure. Getting the document into a URL means every one of those becomes a percent escape, and getting it back out means every one has to survive.

This page does one thing the generic URL encoder cannot: it loads the document first. YAML's most common fault is a tab used for indentation, which the spec forbids outright and which is completely invisible in an editor — a tab and four spaces look identical. Encoding a document with a tab in it succeeds, and the failure surfaces somewhere else entirely. Here it is caught with a line number before anything is escaped.

The other thing worth knowing is what the escaping costs. The sample below is 133 characters and encodes to 199 — about a 50% increase, which is gentler than XML and similar to JSON. Seven of those extra characters are line breaks: each newline becomes %0A, three characters where there was one. The chip counts them, because on a block-style document that is where the growth actually is.

How to use it

1. Paste the YAML – Type it, paste it, or upload a .yaml or .yml file. A document that will not load stops here — with a specific message about tabs when that is the cause, rather than the generic parse error that leaves you staring at a line which looks fine.
2. Read the line-break count – It tells you how much of the encoded length is structure. If a document is close to the ceiling, that number is the part you cannot do anything about without changing the file.
3. Keep the style on "One value" – That is encodeURIComponent. "Whole URL" leaves &, = and # unescaped — and # starts a YAML comment, so a document with one will be cut at it by the URL rather than by the parser.
4. Check the length against 2000 – There is no limit in RFC 3986; the ceiling comes from proxies, load balancers and server request-line buffers. A realistic config fragment will often exceed it, and when it does the answer is a POST body rather than a cleverer encoding.
5. Decode it once at the other end – YAML URL Decode unwinds exactly one layer and checks the result still loads, which is the thing worth verifying when indentation had to survive a round trip.

If the YAML is bound for a shell command, remember that %0A is a literal percent-zero-A until something decodes it — so a document that "lost its line breaks" has usually been pasted somewhere that never decoded, not somewhere that mangled them. Check whether the receiving end is decoding at all before assuming the encoding is at fault.

Why there is no "minify" button here

The JSON and XML pages both shrink your document before encoding it, and both are safe doing so because whitespace in those formats is meaningless. YAML is different, and the tempting equivalent — re-emitting the document in flow style — is not a formatting change. Here is the sample put through yaml.dump with flow style, which is exactly what a "minify YAML" feature would do:

# SIM provisioning request
subscriber:
  msisdn: "447700900112"
  iccid: 8901240544102066246
  roaming: true

{subscriber: {msisdn: '447700900112',
 iccid: 8901240544102066000,
 roaming: true}}

# 31 characters saved, and:
#  1. the comment is gone
#  2. the ICCID lost its last
#     three digits, silently

When this comes up

A config override on a webhook or a job trigger

CI systems and job runners often accept a small YAML fragment as a parameter so a run can be started with overrides. The fragment is short by design, which is the one case where YAML in a URL is comfortable rather than a squeeze.

Sharing a Kubernetes manifest snippet in a link

A link that opens a tool with a manifest already loaded is genuinely useful for a review or a bug report. Manifests get long quickly, though, so check the length chip before designing around it — and consider Base64, which is a flat 33% overhead rather than a variable 50%.

Reproducing a parse failure someone reported

A colleague says a config fails to load and pastes it into chat, where the client has helpfully converted tabs, trimmed trailing spaces, or both. Passing the document through a URL preserves it byte for byte, which is often the only way to reproduce a whitespace bug at all.

Checking that indentation survived a round trip

When YAML has passed through several systems, the question is usually whether the structure is still what it was. Encode it here, decode it with YAML URL Decode, and compare — or run both versions through YAML to JSON, where a change in structure is impossible to miss.

What this page does

• Loads the document before encoding, and refuses rather than escaping something that will fail later.
• Names tabs specifically, with the line number — the commonest YAML fault and the one a generic error helps least with.
• Reports line and column from the parser, corrected to be 1-based rather than the 0-based values the library returns.
• Counts the line breaks so you can see what the structure is costing you.
• Encodes the document exactly as pasted. Nothing is reformatted, no comment is dropped, no value is re-typed.
• Notices a multi-document file and says so, since --- separators are easy to forget about when a payload is being passed around.
• Runs entirely in your browser. Nothing you paste is uploaded.

Questions people actually ask

Why can I minify JSON and XML here but not YAML?

Because in those two formats whitespace carries no meaning, and in YAML it carries the structure. The equivalent operation would be re-emitting the document in flow style, which is a rewrite rather than a reformat. Measured on the sample above it saves 31 characters and costs you every comment in the file — and comments are most of the reason people choose YAML over JSON in the first place.

Is that the only thing flow style loses?

No, and the second one is worse because it is silent. Running the sample through a plain yaml.load and yaml.dump turns the ICCID 8901240544102066246 into 8901240544102066000, because the value goes through a JavaScript double on the way and doubles run out of precision around sixteen digits. Nothing warns you. This page never re-emits your document, so it cannot happen here.

What is %0A, and why is there one on every line?

It is the escape for a newline. A URL cannot contain a raw line break, so every one becomes three characters. On a block-style YAML document that is usually the single largest contributor to the encoded length — the sample has seven line breaks, which is 21 of the 66 characters the encoding added.

It says I have a tab. I cannot see one.

That is the entire problem — a tab and four spaces are indistinguishable on screen. YAML forbids tabs in indentation unconditionally, so a single one anywhere in the leading whitespace fails the document. Most editors will show whitespace on request, and most will convert on save; the line number in the bar tells you where to look.

Does the document need a --- at the top?

Not for a single document. You need --- separators when a file holds several, which is common for Kubernetes manifests, and this page tells you how many it found so you can be sure the whole set made it into the parameter. A payload that lost its separators loads as a shorter document without complaining.

Should I use Base64 instead?

For anything above a few lines, probably. Base64 is a flat 33% overhead against the roughly 50% seen here, and the result contains nothing a URL or a shell will react to — which for a format built out of whitespace is a real advantage. YAML to Base64 will give you the comparison on your own document.

Related tools

References

• YAML 1.2.2 — Indentation Spaces – Where tabs are ruled out, in one sentence
• RFC 3986 §2.1 — Percent-Encoding – The rule every escape on this page follows
• js-yaml – The parser behind the checks here