Having fought with YAML just recently I suggest the media type application/garbage. The format is filled with strange footguns.
I can imagine this would have been baffling if I hadn't read about it before. There wasn't actually an elegant solution, but replacing `\n on:` with `\n "on":` was an acceptable hack that took two minutes.
> Section 10.3.2 of [YAML] specifies that only the scalars matching the regular expression `true|True|TRUE|false|False|FALSE` are interpreted as booleans. Older YAML versions were more tolerant (e.g., interpreting `NO` and `N` as `False` and interpreting `YES` and `Y` as `True`). When the older syntax is used, a YAML implementation could then interpret `{insecure: n}` as `{insecure: "n"}` instead of `{insecure: false}`. Using the syntax defined in Section 10.3.2 of [YAML] prevents these issues.
> [YAML] Ben-Kiki, O., Evans, C., dot Net, I., Müller, T., Antoniou, P., Aro, E., and T. Smith, "YAML Ain't Markup Language Version 1.2", 1 October 2021, <https://yaml.org/spec/1.2.2/>.
- Duplicate keys are not allowed
- The fallback schema gives you no Implicit Typing and Direct representations of objects for free (the former explicity, the latter by restricting which tags are allowed). Schemata in general allow for doing the "right thing" for your domain more easily.
But I think the biggest problem for me was every single yaml library I tried in various languages (go, rust, python, ruby) was just not good. IIRC only one of them (rubys syck I think) even supported anchors, which is a yaml standard, and NONE of them could read anchors to know where in the yaml file the scan was happening.
So I wound up having to literally crawl tab/indents, specify what symbol anchors where /& and store that and rebuild everything.
I THOUGHT I could just say "goto &anchor, copy &data to anchor, anchor, anchor, *anchor.." but nothing knew what &anchor was! What's the point of having a spec with &anchor if your library does literally nothing with it?
I'm sure someones dealt with this probably in a more elegant way than me.
I feel like for multi-line strings, I almost always use |, and only |. It takes the indented block as-is, which I feel like is going to be what you'd want … always?
I think maybe once, ever, I used > to fold some whitespace…?
I know the chomping & indent indicators exist, but I feel like I've only ever seen those in programmatically generated YAML. I have trouble envisioning a real-world use-case that is going to make me pull them out. They're a facet of the language that feels as if it exists solely for a processor that might need to emit any possible string, which | would not permit, and the inline strings might be uglier.
That said … there is a post like yours in every YAML thread. But I think those of us that understand YAML … I'm having a hard time grokking what you're doing that causes consternation.
What if you are writing primarily paragraphs?
What if you want extra blank lines at the end of a block? Or no carriage return at all?
In my reading, unscientifically I feel I see the `>` text formatter most often, then almost as often `|`, then `>-` occasionally, then `>+` just one time.
I'm not usually putting prose into YAML, outside of comments. I think most of my blocks are scripts, small data files, long queries, the like. That's sort of why I was looking for a (perhaps non-hypothetical) use case.
Except it doesn't. Try using
steps:
- run: |
> f echo not redirected
true