Why did my comments disappear in YAML to JSON?

JSON has no comment syntax. A converter rebuilds a JSON value from the parsed YAML, so # comments are not in the output.

Is a hash inside a quoted YAML string a comment?

No. note: "issue #14" is a string. The characters stay in the JSON. Only a # that starts a comment token is dropped.

Does kubectl keep comments when it reads YAML?

kubectl parses YAML and talks to the API in JSON. Comments never reach the apiserver. The live object is not your file with notes attached.

Why YAML to JSON loses comments (and what to do)

JSON is a data format, not a document format. A YAML comment is a token in the source file. After a parse, that token is gone, so any JSON you write cannot include it.

What the parser actually keeps

YAML is a sequence of tokens: keys, values, indentation, and comments. A parser builds a value: maps, lists, strings, numbers, booleans, null. Comments are not part of that value. When ConfigKit converts YAML to JSON, it stringifies the value. There is nowhere to put # keep the cache warm.

# keep this out of the JSON
service: configkit
port: 8080

The JSON is an object with service and port. The first line is not represented. The YAML to JSON without uploading page reports that comments were dropped. That notice is the feature. A converter that silently stripped comments would look as if the input never had them.

JSON has no comment syntax

RFC 8259 JSON does not allow //, /* */, or #. A trailing comma after the last property is also illegal. If you paste a comment into the JSON side of a converter, that is a syntax error. ConfigKit writes no output and does not try to repair the text. JSONC, JSON5, and some editor settings are other languages. They are not JSON, and this site does not treat them as JSON.

Some APIs accept a $comment keyword inside JSON Schema. That is a string property in a schema document, not a YAML # line. Do not expect a general YAML-to-JSON converter to invent $comment keys from your source comments. It would be guessing which comment belongs to which key.

A hash that is not a comment

YAML only treats # as a comment when it starts a comment token, usually after whitespace outside quotes. Inside a quoted string, it is data:

note: "issue #14"
path: "/tmp/#scratch"

Both values survive as JSON strings. If a comment seems to have “stayed”, it was never a comment. If a value vanished, it was not quoted and the parser read it as a comment. Quote the string, or put the hash somewhere YAML does not treat as a comment start.

kubectl does the same thing

kubectl apply -f app.yaml parses YAML in the client and sends JSON to the apiserver. Comments in the file are for you. They are not stored on the object. kubectl get -o yaml prints a generated YAML document from the live object. It will not round-trip your comments, your key order, or your blank lines. That is why a GitOps repo is the source, not the cluster.

The error error converting YAML to JSON is kubectl failing while building that JSON. It is a syntax problem, not a missing comment. See error converting YAML to JSON for the part after the colon. A Kubernetes YAML syntax check reports the same class of parse error without talking to a cluster.

What to do instead

Keep YAML (or TOML) as the file people edit. Generate JSON only when a tool requires it: a browser fetch, a JSON Schema validator, a structured log. Put longer notes in a README next to the config, or in a description field that is real data. If a field must carry an annotation, make it a key with a string value, not a comment.

For Kubernetes, metadata.annotations is the supported place for notes that must travel with the object. They are still data. They will show up in kubectl get -o json. They are not a replacement for a paragraph in git, and they should not hold secrets.

If you only needed JSON to pretty-print or to share a snippet, stay on YAML. The YAML formatter rewrites indentation and keeps comments. Conversion is the step that throws them away. Use it when the consumer is JSON, not when you wanted a second view of the same file.

Checking the drop on this site

Paste a YAML document that starts with a comment into YAML to JSON. The output object should match the values. The status should mention comments. Disconnect the network after the page loads if you want to confirm the conversion is local. Nothing about “offline” brings comments back: the limit is the JSON grammar, not the network.

FAQ

Why did my comments disappear in YAML to JSON?: JSON has no comment syntax. A converter rebuilds a JSON value from the parsed YAML, so # comments are not in the output.
Is a hash inside a quoted YAML string a comment?: No. note: "issue #14" is a string. The characters stay in the JSON. Only a # that starts a comment token is dropped.
Does kubectl keep comments when it reads YAML?: kubectl parses YAML and talks to the API in JSON. Comments never reach the apiserver. The live object is not your file with notes attached.