Last reviewed: 2026-08-02
Account Contract
Canonical object: Account
Required fields: - id - company_id - code - name - account_type - normal_balance - status - posting_status - effective_from - source - version
Optional fields relevant to standard-chart continuity: - standard_account_key
Allowed account types: - asset - liability - equity - income - expense
Allowed normal balances: - debit - credit
Allowed statuses: - active - inactive - retired
Allowed posting statuses: - posting - non_posting
Allowed sources: - booksplus_standard - module - imported - user_created
Rules:
- Account code must be unique within a company.
- Account identity is immutable and independent from visible code and name.
- source records account origin. Starter-chart adoption must not rewrite it.
- standard_account_key is an immutable company-scoped logical identity for a
starter-chart account. It is independent from source, code, and name.
- A nonblank standard_account_key may be assigned to a pre-existing account
only through the reviewed starter-chart collision workflow.
- A standard_account_key must be unique within a company and must not be
replaced by a different key.
- Account codes are strings and must preserve leading zeros.
- Accounting behavior must not infer classification from account-number patterns.
- Non-posting report headings are not accounts.
- Posting normally requires an active account.
- Routine posting requires posting_status posting and direct posting to be allowed.
- Correction adjustments require active accounts with posting status posting
and direct posting allowed.
- Full reversal may reuse an inactive or retired historical account only when
the target journal-entry line references that exact same-company account id.
- Replacement accounts, current codes, names, or roles must not redirect a
full reversal.
- Used accounts may be retired but not deleted.
- Used accounts may be renamed or renumbered with audit history.
- Historical entries must retain their original account reference.
- Live Reporting resolves current account code and name from immutable account
id. A persisted ReportSnapshot preserves the captured code, name, account
type, and normal balance without rewriting Account or JournalEntry history.
- Financial-statement classification uses account type. Account code, name,
number range, provider vocabulary, and screen position must not select a
report section.
- Account maintenance retirement requires an active replacement account.
- Retired accounts must identify a replacement account when a replacement is required by workflow.
Validation expectations:
- code uniqueness by company.
- account_type, normal_balance, and status values use the stable snake_case contract values defined by this contract.
- posting_status and source values use stable snake_case contract values.
- standard_account_key is either absent or nonblank and unique by company.
- status values support active, inactive, retired, and historical references.
- account references preserved for existing journal lines.
- account-maintenance retirement requires an active replacement account.
- singleton semantic roles are enforced explicitly by role cardinality.
- correction historical-account exceptions preserve the target line's
immutable account reference.
Related truth pages:
- company.contract.md
- ../accounting/accounts.md
- ../vision-and-product-principles.md
- accounting-correction.contract.md
- reporting.contract.md