You should track your finances in TOML

No, really! Let me explain.

I am quite particular with my finances. Having a proper accounting system helps me keep control of my spendings and what I am saving. Being a pretty nerdy guy, I quickly gravitated towards the plain text accounting movement, with which I ensure that I can control my data, switch systems if I want and do custom scripting around my ledger. I won’t delve into the details here, but the plaintextaccounting.org website is a great source of information, and I recommend reading through the Newcomer FAQ if you want an introduction to the concept.

The most popular tools for plain text accounting today are Beancount, Ledger and hledger. They are all fantastic tools, using similarly inspired DSLs that are pretty easy to learn. However, their syntax deviate in subtle ways. Here is an example entry written in Ledger first and then Beancount:

2023/11/06 My local grocery store | Grocery shopping
  Assets:ExampleBank:Checkings  $-20
  Expenses:Food:Groceries        $20

2023-11-06 * "My local grocery store" "Grocery shopping"
  Assets:ExampleBank:Checkings  -20 USD
  Expenses:Food:Groceries        20 USD

They are not compatible with eachother, and converting between the two is non-trivial. There are countless examples of features (transaction flags, prices, capitalization conventions, metadata, etc.) that are non-interoperable like this.

Now say you want to write some scripts for processing your journal. This means you’ll have to scour the internet for a parser supported by your language of choice, or write one on your own. Let me tell you, they are not abundant, and good luck finding a non-official library that is regularly updated. You might get forced to use a language you would not choose yourself, just to get some simple processing done.

Many of the reasons these tools have opted for a DSL, is to keep the amount of necessary typing to a minimum—an admirable goal which they achieve quite well in my opinion. However, most users use automated scripts, data-entry tools or at the least some editor completion to insert their data. Why, then, can’t we just use a standard plain text data serialization language?

Advantages of using a proper data serialization format

The advantages are obvious, given my gripes listed above; almost all of them are solved:

• Interoperability: It is trivial to convert from one data format to another. Just look at the serde framework for Rust, or the countless number of conversion tools available online.
• Language support: You can expect to find a high-quality maintaned library for parsing any of the big data formats in most languages. These often also deserialize into native data-structures, which should be easier to handle when scripting.
• Standard: This hooks a bit into interoperability, but the key here is that you can expect your data to be easily used by or ported to any tool or service you want to use in the future. Not only that, but having a simple map to e.g. JSON makes the path to a web-accessible API quite clear.

Why TOML?

With these ideas in mind, why am I saying that TOML specifically is the solution? Well, the homepage says it all:

A config file format for humans.

The whole ethos around plain text accounting is that it can be read in it’s raw form and edited by hand if so desired. These goals are at the core of TOMLs design. Here is the equivalent transaction I showed above, written in my proposed TOML ledger specification:

[[transaction]]
date = 2023-11-06
description = "Grocery shopping"
payee = "My local grocery store"
postings = [
  { account = "Assets:ExampleBank:Checkings", amount = -20, currency = "USD" }
  { account = "Expenses:Food:Groceries", amount = 20, currency = "USD" }
]

Definitely more verbose, yes, but still reasonably short and totally legible (and perhaps even easier to understand without knowing the syntax beforehand.) Note also that TOML has a datetime type, which is perfectly suited for this use case.

Now this example leaves a lot to be desired. Evidently, writing out the currency in this way for each posting is not ideal, but could be solved by allowing the user to set a default currency. Accounts also borrow the colon-separated syntax from ledger, but I think this is also something that could be improved upon. There are also a lot of crucial details I have glossed over here—for example currency prices, posting metadata, balance assertions and more—but I would say these are all pretty low-hanging fruit.

If you like the concept and have thoughts or ideas that you would like to share, please send an email to my public inbox, and I’ll be happy to discuss! I’m doing some testing in a CLI called mynt, which initially is for personal use, but feel free to have a look at it for reference, contribute a patch if you see an improvement that can be made or even try it out yourself.