Tags

Tags are key/value pairs that allow you to add custom context 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.

Caution

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.

customer:ruth

reservation:9f89c641-e333-4b31-b66c-133ff35f3f60

transmission_type:wire

data:{ "customer":8191234, "order": "b405988cd7f089810"}

key: ab:cd:ef

value: 123

The Tag Contract

One of the big differences between String Theory and more classic ledger 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:

Any tag added to a knot will be preserved on all of its descendant knots, unless you explicitly remove or change it.

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 your 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.

Groups / Threads and Tags

Groups and threads do not have tags of their own. Tags only exist on knots. So, when we talk about tags for a group or thread, what we actually mean is the combination of tags from all the current knots that belong to that group or thread. For clarity, we’ll call this set of all knots in a group or thread the “population”.

We often conceptualize all the knots in a population as a single entity, so we let you operate on tags for that entity, too. You can add or change tags for all knots in a group or 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 population have the same value for the tag.
2. You cannot change a tag’s value unless all knots in the population have the same value.

If you run afoul of either of these restrictions you can get around it by specifying the knots you want to change, instead of only providing the population. The guiding principle 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 population don’t agree there is no safe way to do this at the population level. Note: you can always add tags to a population that are not present on any knots.