Glossary¶

Definitions of terms used throughout the Plain Text Accounting Standards.

A¶

Account¶

A named container for tracking financial positions. Consists of colon-separated components starting with a root type. The five standard root types are: Assets, Liabilities, Equity, Income, Expenses.

Example: Assets:Bank:Checking

Amount¶

A quantity paired with a commodity/currency. Represents a specific value in a specific denomination.

Example: 100.00 USD

Assertion (Balance Assertion)¶

A directive that verifies an account's balance matches an expected value at a specific date.

Example: 2024-01-15 balance Assets:Checking 1000 USD

Augmentation¶

Adding units to an inventory. The opposite of reduction. Creates a new lot or merges with an existing identical lot.

B¶

Booking¶

The process of matching a reduction (sale/withdrawal) against existing lots in an inventory. Common methods include STRICT, FIFO, LIFO, AVERAGE, and NONE.

Booking Method¶

Algorithm for selecting which lot(s) to reduce when multiple lots match:

STRICT: Requires unambiguous match; error if multiple lots match
FIFO: First In, First Out; oldest lots first
LIFO: Last In, First Out; newest lots first
AVERAGE: Weighted average cost basis
NONE: No matching; allows mixed-sign inventories

C¶

Commodity¶

An identifier for a denomination. MAY represent fiat currency (USD, EUR), stocks (AAPL, GOOG), crypto (BTC), or custom units (VACHR). Also called "currency" in some contexts.

Cost¶

The acquisition price of a position, including per-unit price, currency, date, and optional label. Stored with positions to track cost basis.

Syntax: {100.00 USD, 2024-01-15, "lot-1"}

Cost Basis¶

The total acquisition cost of a position. Used for calculating capital gains.

Formula: units × cost_per_unit

Cost Specification¶

A pattern for matching lots during reduction. MAY partially specify cost, date, and/or label.

D¶

Decimal¶

An exact decimal number (not floating point). Used for all financial calculations to avoid rounding errors.

Directive¶

A dated instruction in a journal file. Common types include: transaction, balance, open, close, commodity, pad, event, note, document, price.

Double-Entry Bookkeeping¶

An accounting method where every transaction affects at least two accounts, with debits equaling credits. The fundamental principle underlying plain text accounting.

F¶

Flag¶

A character indicating transaction status:

* - Complete/cleared
! - Pending/incomplete

I¶

Interpolation¶

Automatically calculating a missing posting amount to make a transaction balance. At most one posting per currency MAY be interpolated.

Inventory¶

A collection of positions (lots) held in an account. Tracks units, costs, dates, and labels for each lot.

J¶

Journal¶

A file containing accounting directives. The primary input format for plain text accounting tools.

L¶

Ledger¶

The complete processed state of a journal file, including all directives, computed inventories, validation errors, and options.

Link¶

An identifier connecting related transactions. Syntax varies by format (e.g., ^invoice-123 in Beancount).

Lot¶

A position with a specific cost basis, acquisition date, and optional label. Lots are tracked separately for tax purposes.

M¶

Metadata¶

Key-value pairs attached to directives or postings for custom annotations.

Example: receipt: "photo.jpg"

N¶

Narration¶

The description text of a transaction explaining its purpose.

O¶

Operating Currency¶

A currency designated as primary for reporting. Multiple MAY be specified.

P¶

Pad¶

A directive that automatically generates a balancing transaction to satisfy a subsequent balance assertion.

Payee¶

The other party in a transaction (merchant, employer, etc.).

Plain Text Accounting (PTA)¶

A method of tracking finances using human-readable text files. Characterized by:

Simple, version-control-friendly file formats
Command-line tools for processing and reporting
Double-entry bookkeeping principles

Position¶

Units of a commodity held at a specific cost. The building block of inventories.

Structure: units: Amount, cost: Option<Cost>

Posting¶

A single line within a transaction, specifying an account and amount change.

Price¶

The current market value of a commodity in terms of another commodity. Used for valuation, not for transaction balancing.

Syntax: @ 150.00 USD (per-unit) or @@ 1500.00 USD (total)

R¶

Reduction¶

Removing units from an inventory. Triggers the booking algorithm to match against existing lots.

Root Type¶

One of the standard account categories. Traditionally: Assets, Liabilities, Equity, Income, Expenses.

S¶

Scale¶

The number of decimal places in a number. Used for inferring tolerance.

Example: 100.00 has scale 2; 100 has scale 0.

Span¶

A range of bytes or characters in source code, used for error reporting.

Source Location¶

File path, line number, and column pointing to a position in source code.

T¶

Tag¶

An identifier for categorizing transactions. Syntax varies by format (e.g., #vacation-2024 in Beancount).

Tolerance¶

The maximum acceptable difference when checking if values are equal. Often inferred from decimal precision.

Transaction¶

The primary directive type representing a financial exchange between accounts. MUST balance (sum of weights equals zero).

U¶

Units¶

The quantity component of an amount, without the commodity.

W¶

Weight¶

The balancing contribution of a posting to a transaction. Calculated as:

Simple amount: units
With price: units × price
With cost: units × cost
With both: units × cost (price ignored for balancing)

Symbols¶

`*` (Star)¶

Transaction flag indicating "complete" or "cleared".

`!` (Bang)¶

Transaction flag indicating "pending" or "needs review".

`@` (At)¶

Price annotation (per-unit). Example: @ 1.20 CAD

`@@` (Double At)¶

Total price annotation. Example: @@ 120.00 CAD

`{}` (Braces)¶

Cost specification. Example: {100 USD}

`{{}}` (Double Braces)¶

Total cost specification. Example: {{1000 USD}}

`~` (Tilde)¶

Explicit tolerance in balance assertions. Example: 1000 USD ~ 0.01