Open Directive¶

Overview¶

The open directive declares an account's existence and optionally constrains its allowed currencies and booking method.

Syntax¶

open = date WHITESPACE "open" WHITESPACE account
       [WHITESPACE currency_list]
       [WHITESPACE booking_method]
       (NEWLINE metadata)*

currency_list  = currency ("," currency)*
booking_method = string

Components¶

Date¶

The date the account becomes available for use. Postings to this account before this date will produce validation errors.

Account¶

The full account name including root type:

2024-01-01 open Assets:US:BofA:Checking
2024-01-01 open Liabilities:CreditCard:Chase
2024-01-01 open Expenses:Food:Groceries

Currency Constraint¶

Optional list of allowed currencies:

; Allow only USD
2024-01-01 open Assets:Checking USD

; Allow multiple currencies
2024-01-01 open Assets:Brokerage USD,EUR,AAPL,MSFT

; Allow any currency (default)
2024-01-01 open Expenses:Food

When specified, postings using other currencies will produce validation errors.

Booking Method¶

Optional string specifying how lot matching works for reductions:

2024-01-01 open Assets:Brokerage USD,AAPL "FIFO"
2024-01-01 open Assets:Retirement USD,VTSAX "LIFO"
2024-01-01 open Assets:Trading USD,BTC "STRICT"

Booking Methods¶

Method	Description
`STRICT`	Require exact lot specification (default)
`STRICT_WITH_SIZE`	Like STRICT but also requires matching size
`FIFO`	First-in, first-out
`LIFO`	Last-in, first-out
`HIFO`	Highest cost first
`NONE`	Allow any reduction (no lot tracking)
`AVERAGE`	Use average cost basis

Booking methods MUST be uppercase. Lowercase methods (e.g., "fifo") are rejected.

See booking.md for detailed booking method documentation.

Examples¶

Basic Account¶

2024-01-01 open Assets:Checking

With Currency Constraint¶

2024-01-01 open Assets:US:Schwab:Cash USD
2024-01-01 open Assets:EU:Bank:Cash EUR

With Booking Method¶

; Retirement account with FIFO booking
2024-01-01 open Assets:Retirement:401k USD,VTSAX "FIFO"

; Trading account requiring explicit lot selection
2024-01-01 open Assets:Trading:Coinbase USD,BTC,ETH "STRICT"

With Metadata¶

2024-01-01 open Assets:Checking USD
  institution: "Bank of America"
  account-number: "****1234"
  opened-by: "online"

Account Naming¶

Root Types¶

Every account MUST start with one of five root types:

Root	Purpose	Normal Balance
`Assets`	Things you own	Debit
`Liabilities`	Things you owe	Credit
`Equity`	Net worth, opening balances	Credit
`Income`	Money received	Credit
`Expenses`	Money spent	Debit

Component Rules¶

Components are separated by colons (:)
Each component MUST begin with an uppercase ASCII letter (A-Z) or digit (0-9)
Subsequent characters may be letters (including UTF-8), numbers, or hyphens
UTF-8 characters are allowed ONLY after the first ASCII character
Components MUST NOT contain spaces

Valid Examples¶

Assets:US:BofA:Checking
Liabilities:CreditCard:Chase-Sapphire
Expenses:Food:Groceries
Income:Salary:2024
Equity:Opening-Balances

Invalid Examples¶

assets:Checking           ; lowercase root
Assets:checking           ; lowercase component
Assets:My Checking        ; space in component
Assets::Checking          ; empty component
Savings:Account           ; invalid root type

Validation¶

The following conditions produce validation errors:

Condition	Error Type
Account already opened (duplicate open)	`ValidationError`
Invalid account name	`ParserError`
Posting uses currency not in constraint list	`ValidationError`
Invalid booking method	`ParserError`

Auto Accounts Plugin¶

Implicit account opening (creating accounts on first use) is supported via a plugin:

plugin "beancount.plugins.auto_accounts"

When enabled, accounts are automatically opened on their first use. This is NOT recommended for production ledgers as it bypasses the validation that ensures all accounts are explicitly declared.

Relationship to Close¶

Accounts opened with open can be closed with close:

2020-01-01 open Assets:OldAccount USD
; ... transactions ...
2024-12-31 close Assets:OldAccount

After closing, the account cannot be used in new postings.

Implementation Notes¶

Store the open date for lifecycle validation
Store currency constraints for posting validation
Store booking method for inventory operations
Track all opened accounts for reference validation