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, Transaction Data Sharding, Usage Manual and tackler.conf for further details how to define used storage system and ideas for different sharding schemes.

Journal Format Syntax

Version v2 Journal entry Comments

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 must begin with a UTF-8 letter or sign (over 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 for calculations.
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 names begin with a UTF-8 letter. Then letters, digits, middle dot `·`, hyphen `-` and underscore `_` are allowed, but no spaces. All commodities must be defined in strict-mode. Commodity is mandatory in strict mode if `permit-empty-commodity` is not true. See accounts.conf for full details.
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 Accounting Auditing and tackler.conf for further information. Transactions must have UUIDs, if deterministic, stable and "distributed transaction producers"-proof 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	Optional Geo Location for Transaction Since v0.31
Metadata: Txn Tags	2019-05-01 'Txn with tags # tags: cranberry, caramel Expenses:Ice_cream 2.12 Assets:Cash	Optional transaction tags Txn tags could be used select subselection of txns for reports. See: Txn Tag Filters Since v0.34
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.

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 must begin with a UTF-8 letter or sign (over 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 for calculations.

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 names begin with a UTF-8 letter. Then letters, digits, middle dot ·, hyphen - and underscore _ are allowed, but no spaces.

All commodities must be defined in strict-mode. Commodity is mandatory in strict mode if permit-empty-commodity is not true. See accounts.conf for full details.

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 Accounting Auditing and tackler.conf for further information.

Transactions must have UUIDs, if deterministic, stable and "distributed transaction producers"-proof 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

Optional Geo Location for Transaction
Since v0.31

Metadata: Txn Tags

2019-05-01 'Txn with tags
 # tags: cranberry, caramel
 Expenses:Ice_cream 2.12
 Assets:Cash

Optional transaction tags
Txn tags could be used select subselection of txns for reports. See: Txn Tag Filters
Since v0.34

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.