The YAML threshold

I’m not using YAML a lot. If I need an easy-to-read configuration file, I’m using TECL, but usually XML serves me fine. It is a one-stop-shop for a lot of stuff; anything not code usually can be done nicely with XML. And its verbosity is not really a problem with the current bandwidths, unless you need to send a lot of data. And it is easy enough to read for a human.

But I do hear a lot of wining about YAML; “I’ve been searching for ages trying to find an indent typo“, especially from the Kubernetes community where the YAML files can get large quickly.

Now. Let me be very clear: using indentation as a meaningful value is not a good idea. No really, it is not. It’s too fragile. I know it reads nicely, and that is exactly what it is for, so we humans can more clearly see the blocks. But those blocks better be defined discretely, so the indentation can be derived. And don’t even get me started on those cryptic !! |- > | meta instructions! Reminds of the the days that there were competitions to make as unreadable compact C programs as possible, because the idea was that less code was easier to maintain. Which is correct… Up to a point.

And the “up to a point” applies to YAML as well. Readability and stability is a balance between being concise and verbose. YAML in it’s basic usage, a small file without meta instructions, is nice. But in a larger file, where blocks no longer fit on one screen, it isn’t anymore. There is a threshold in the number of lines after which YAML should not be used anymore. And that aren’t too many.

But unfortunately some projects have chosen to use it, so what can you do?

Well. You can use another format and convert it on the fly. Like… XML!

<?xml version="1.0" encoding="UTF-8"?>
<xml2yaml>
	<invoice>34843</invoice>
	<date>2001-01-23</date>
	<bill-to id="id001">
		<given>Chris</given>
		<family>Dumars</family>
		<address>
			<lines>
				458 Walkman Dr.
				Suite #292
			</lines>
			<city>Royal Oak</city>
			<state>MI</state>
			<postal>48046</postal>
		</address>
	</bill-to>
	<ship-to ref="id001"/>
	<product>
		<_>
			<sku>BL394D</sku>
			<quantity>4</quantity>
			<description>Basketball</description>
			<price>450.00</price>
		</_>
		<_>
			<sku>BL4438H</sku>
			<quantity>1</quantity>
			<description>Super Hoop</description>
			<price>2392.00</price>
		</_>
	</product>
	<tax>251.42</tax>
	<total>4443.52</total>
	<comments replaceNewlines="true">
		Late afternoon is best.
		Backup contact is Nancy
		Billsmer @ 338-4338.
	</comments>
	<_ key="brilliant idea">Allowing spaces in keys<_>
</xml2yaml>

And pull that either through the command line tool or Maven plugin.

<plugin>
    <groupId>org.tbee.xml2xxx</groupId>
    <artifactId>xml2yaml-maven-plugin</artifactId>
    <configuration>
        <inputFile>src/main/resources/example.xml</inputFile>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>convert</goal>						
            </goals>
        </execution>
    </executions>
</plugin>

And TADAAAA… Nicely formatted and correctly indented.

invoice: 34843
date: 2001-01-23
bill-to: &id001
  given: Chris
  family: Dumars
  address: 
    lines: |
      458 Walkman Dr.
      Suite #292
    city: Royal Oak
    state: MI
    postal: 48046
ship-to: *id001
product: 
  - sku: BL394D
    quantity: 4
    description: Basketball
    price: 450.00
  - sku: BL4438H
    quantity: 1
    description: Super Hoop
    price: 2392.00
tax: 251.42
total: 4443.52
comments: >
  Late afternoon is best.
  Backup contact is Nancy
  Billsmer @ 338-4338.
brilliant idea: Allowing spaces in keys

Amazing what lockdowns due to Covid can result in. 😀 But one thing is certain: “replaceNewlines” is a lot more readable than “>”…

Or was it “|”?

Or “!!”?

Sigh…

Anyhow, XML2YAML; it works, it’s open source, it’s on Maven central. Use it. Or not.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.