Tags

Tags are key/value pairs that allow you to add context data to your knots. You can use that context to better categorize, understand, filter, and search through the money in your system. Tags are entirely in your control, and have very few restrictions.

Tag restrictions

1. Tag keys cannot contain a colon (:) character
2. Tag values must be text (a string, in programmer terms)
3. Tag keys and values cannot contain any serialized or complex object data*1.

*1 the system only enforces that the value is text. It is possible to serialize data into values, but it is highly discouraged. Consider using multiple keys if you need multiple pieces of data.

Tag Examples

String Theory often display tags in the style key: value. Here are some examples of good and bad tags.

The Tag contract

One of the big differences between String Theory and more classic ledgers systems is that with String Theory the context of a piece of money follows it throughout its lifecycle, instead of just until it leaves its current account. Tags are your way of adding your own context into that chain.

The contract between you and String Theory for tags is as follows:

Inherited Context Example

Let's say that you are a small art business and you just made a big sale (congratulations!). You tag the deposit with some helpful information so you can easily remember where that money came from. You add painting: glowing ferns and customer: ruth.

A month goes by, and you're business account is low on cash. You remember you just made a big sale... so what happened to all that money? Luckily, you added some helpful tags so String Theory makes it easy to figure out. You search for all the knots with the tag painting: glowing ferns and you find the deposit thread for that sale.

Tags & Threads

Threads do not directly have tags of their own. Instead, the tags of a thread are the combination of all the knots that belong to that thread. The reason for this is that threads don't actually contain any information, they just have a series of knots that store the actual value and data.

You can add or change tags for all knots in a thread either through String Theory's UI or through the API. However, there are some specific restrictions:

1. You cannot remove a tag unless all knots in the thread have the same value for the tag.
2. You cannot change a tag's value unless all knots in the thread have the same value.

If you fall afoul of either of these restrictions you can get around it by specifying the knots you want to change, instead of only providing the thread. The general idea is no blind updates are allowed. If you want to change a value you have to know what it is, and when many knots in the thread don't agree there is no way to do this at the thread level. Note: you can always add tags to a thread that are not present on any knots.