Journal Format

Tacklers journal is based on idea of plain text files, where each accounting record is written in human readable and editable form into those text files. This idea of text based double-entry accounting was invented and pioneered by John Wiegley in 2003.

Tackler Ain’t Calculator and Kernel for Ledger Equivalent Records.
Why not? Because it uses simplified syntax.

Journal files

Journal can be a single file or it can be split on transaction level into multiple files (shards).

See general Journal Documentation, Usage Manual and tackler.conf for further defails how to define used storage system and ideas for different sharding schemes.

Journal Format Syntax

Version v2 Journal entry Comments

Basic example

2017-01-01
 Assets:Checking 500.00
 Equity:Assets

2017-01-05 'Shopping on farmer's market
 Expenses:Groceries 50.00
 Assets:Checking

This is sequence of Transactions (Txns). There could one or many Txns per input file.

See Transaction data sharding for ideas how to store journal.

Basic transaction

DATE [CODE] [DESCRIPTION]
 ACCOUNT  AMOUNT
 ACCOUNT  [AMOUNT]

Transaction’s content (comments and account postings) must be intented at least by one space.

There must be two or more accounts (postings) which must have zero sum if all accounts have amount. Account’s amount can not be zero.

Amount of last account could be omitted, in that case it will be calculated automatically.

There has to be at least one space between account and amount. If compatibility with other systems is needed, then two spaces should be used.

Dates and Timestamps

YYYY-MM-DD
YYYY-MM-DDTHH:MM:SS[.SSS]
YYYY-MM-DDTHH:MM:SS[.SSS]Z
YYYY-MM-DDTHH:MM:SS[.SSS]±hh:mm

e.g.

2016-12-31
2016-12-31T13:01:01
2016-12-31T13:01:01.123
2016-12-31T13:01:01Z
2016-12-31T13:01:01+02:00
2016-12-31T13:01:01.123456789+02:00

These are ISO-8601 dates and times with up to nanosecond resolution.

  • If time part is missing then 00:00:00 is used.

  • If Offset is missing then offset based on configured timezone/offset is used.

Transaction code

DATE [(code)]

e.g.

2017-01-01 (#123)
 Expences:Jäätelö   2
 Assets:Cash

Optional transaction code, this could be check number, wire transfer id or delivery tracking number, for example.

Code can not contain characters:
' ( ) [ ] { } < >

Transaction description
(note)

DATE [CODE] ['description]

e.g.

2019-03-16 (#125) 'It was 125th Ice Cream!
 Expenses:IceCream 2
 Assets:Cash

2019-03-16 'Ice cream 'n soda!
 Expenses:BostonCooler 3
 Assets:Cash

Optional transaction description, this is textual note or subject line of transaction.

There must be '-prefix for description, and description is all text until whitespace and newline at the end of line.

Account names

TOPACCT[:SUBACCT[:...]]

e.g.

Expenses:ice_cream
Expenses:jäätelö:mansikka-vadelma
Expenses:crème·glacée
Expenses:мороженое
Expenses:アイスクリーム
Expenses:風:空
Credit_Card:1234567890

Top-account names begin with a UTF-8 letter or sign (cover 130 languages and code blocks are supported).

Then letters, digits, middle dot ·, hyphen -, underscore _ are allowed in account names, but no spaces.

Sub-accounts are separated by :. Sub-accounts can start with numbers and be all numeric.

All accounts must be declared in Chart of Accounts, or accounts.strict must be set to false. See accounts.conf for full details.

Amounts

1234567890.123456789
Output truncation:
  1.123456701 is printed as
  1.1234567   with scale.max=7

  1.12345675  is rounded (HALF_UP) as
  1.1234568   with scale.max=7

Default output scale is is between 2..7 decimal points. This is can be configured by reporting.scale.{min, max} in tackler.conf.

Tackler uses decimal floating-point numbers of arbitrary precision (Scala BigDecimals) for calculations. By default, the precision approximately matches that of IEEE 128-bit floating point numbers (34 decimal digits).

Commodities

2017-05-01 'In Sweden
 Expences:Ice·Cream  200 SEK
 Assets:Cash

2018-07-01 (mix-1234) 'tmx 18/45 D12L
   ; This mix used 26 bar of Helium
   Gas:He:Storage·Tank:102  247 He·bar
   Gas:He:Stogare·Tank:102 -273 He·bar
   Mixer:diverX:He

Commodity of posting
Commodity is mandatory, if accounts.strict is set true and permit-empty-commodity is false.

Commodity names begin with a UTF-8 letter. Then letters, digits, middle dot ·, hyphen - and underscore _ are allowed, but no spaces.

In strict-mode, all commodities must be defined. See accounts.conf for full details.

See Commodities for general info.

Value positions

2017-05-01 'Value pos. with unit price (SEK -> €)
 Expences:Ice·Cream  200 SEK @ 0.1039 €
 Assets:Cash  -20.78 €

2017-05-01 'Value pos. with total price (SEK -> €)
 Expences:Ice·Cream  200 SEK = 20.78 €
 Assets:Cash  -20.78 €

Optional value position for posting
This is mandatory for mixed commodity transaction, see Currencies.

PnL: Opening position

2017-05-01 'Selling one Acme Inc.
 Stock:Shares -1 ACME·INC {120 EUR} @ 123 EUR
 Assets:Cash 123 EUR

Optional opening position for posting
Currently opening position is valid input, but it is not used. This is planned feature. See Currencies

Metadata: UUID

2017-01-01 'Txn with UUID
 # uuid: 83976d4b-8ea8-4cec-804f-931e4f171c3b
 Expenses:Ice_cream 2.12
 Assets:Cash

Optional transaction metadata (uuid)
This is transaction’s unique identifier (UUID).

Transaction UUID is mandatory if txn-set-checksum calculation is activated. See tackler.conf and TEP-1007: Txn Set Checksum for further information.

Transactions must have UUIDs, if fully deterministic, stable and "distributed transaction producers"-safe sort order is needed for register report or identity export.

Metadata: Location

2019-05-01 'Txn with Location
 # location: geo:60.167,24.955,5
 Expenses:Ice_cream 2.12
 Assets:Cash

Comments

2017-01-01 'Txn with comment
 ; txn level comment
 Expenses:groceries 12.00 ; posting comment
 assets:checking

Optional transaction comment
There must be space after ; character.

Transaction comments

2017-01-01 'Txn with multiline comment
 ; it was warm
 ; and sunny day
 Expenses:Jäätelö 2.12
 Assets:Cash

Optional transaction comment
This can span over multiple lines. There must be space after ; character.

Posting comments

2017-01-01 'Posting with comment
 Expenses:Jäätelö 2.12 ; Strawberry ice cream!
 Assets:Cash

Optional posting comment
There must be space after ; character.