Metadata Syntax Required

[the-solipsist]

Currently, hledger needs generalized metadata syntax for a number of situations.

Financial Year

Currently the --yearly and --quarterly flags will create columns as per the calendar year / quarter starting on January 1 and ending on December 31. However, most businesses will need to create report as per their financial year, not the calendar year. Thus, even if a new flag --financial-yearly or --financial-quarterly were to be created, there needs to be a generalized way of telling hledger what the beginning and ends of the financial year/quarters are. This is normally taken in the form month-date. However, some companies, which use a 4-4-5 calendar or a 52-53 week calendar define the financial year and quarters on other bases, involving weeks rather than months. If different kinds of financial years add complexity to the code, then they could be dropped.

Calculation of Capital Gain/Loss

Normally, expenditure incurred wholly and exclusively in connection with the acquisition (whether by purchase, inheritance, etc.) or transfer of capital assets are excluded from the calculation of capital gain, as are costs of improvement. For this, there needs to be either transaction-level or journal-level metadata to indicate which accounts are expenditure incurred in connection with the acquisition/sale of capital assets, which accounts are capital assets, and which accounts are costs of improvement of capital assets. While eventually, there could be separate add-ons that calculate long-term capital gains vs. short term capital gains, even those would need to have this information in the journal/journal metadata.

Cash Flow statement

The generation of cashflow statements require hledger to know what the "current assets" and "current liabilities" to be taken into account in the cashflow statement are. Currently, this is guessed at by hledger through regexes that exclude asset accounts with the words "receivable" and "fixed". There needs to be a way in which users indicate to hledger what should be included and what should be excluded.

Income / Profit & Loss statement

The generation of income statements requires hledger to know what should be taken as revenue and what should be taken as expenses. Not all "R" type accounts and not all "X" type accounts should be included in the Income Statement.

Balance Sheet statement

Same as for the income statement. Additionally, traditionally current assets are listed below non-current assets in the balance sheet statement, and current liabilities are listed below long-term liabilities. (Some liabilities like contingent liabilities aren't normally listed at all, except in a note.)

Currently, for all the above three statements, specific accounts can be included by specifying account names in the cashflow/incomestatement/balancesheet commands and excluded by specifying accounts through not: declarations, but I believe it would be beneficial to have generalized syntax.

These are what I can think of off the top of my head.

[the-solipsist]

Given that account tags were introduced in this commit, would it be beneficial to consider allowing account tags to:

1. Be accessed in queries, and
2. Be able to impact built-in functions (like --yearly, cashflow, incomestatement, balancesheet, etc.)

For (2), it might be beneficial to consider having a YAML file that defines certain parameters for each of these. A sample might look like:

--- 
cashflow: 
  accounts: 
    include-acct: 
      - "Assets:Wallet"
      - "Assets:Cash"
      - "Assets:Bank"
    include-acct-tag:
      - cash
    exclude-acct: 
      - "Assets:Wallet:Points"
      - "Assets:Bank:Fixed Deposits"
yearly: 
  period: 
    from: April
    to: March
...

[simonmichael]

Yes indeed, we need someone to make account tags queryable.

They already influence reports via https://hledger.org/hledger.html#account-types. There's some discussion of customisable reports at #1155.

[the-solipsist]

Actually, thinking about the issue a bit more, this is two separate features:

1. Improving querying + reporting based on metadata specified in the journal.
2. Modifying in-built functions.

Some thoughts on this below.

Improving querying & reporting based on metadata

In-built statements

The issue you linked to is on this point. Given that cashflow, incomestatement, etc., are merely tabular reports based on certain heuristics as to which accounts constitute "Revenues", "Expenses", and so on, they can be easily manipulated. For example, when you generate the cashflow report, you can specify which accounts are not "current assets" or "current liabilities" simply by using not:Assets:NotCurrent:Example, etc. There is no way to ensure that specific accounts should be included.

This is mostly not a problem for incomestatement and balancesheet, but is a problem for cashflow, since identifying "current assets" and "current liabilities" is a harder problem than identifying "revenue", "expense", "assets", "liabilities", and "equity" given that those can be labelled using tags.

So, supporting something like:

account Assets:Accounts Receivable        ; category:current
account Assets:Cash                       ; category:cash
account Assets:Bank:Long Term Deposits    ; category:noncurrent
account Liabilities:Accounts Payable      ; category:current

But being able to generate custom statements out of multiple "balance" queries would solve this issue if "balance" queries can access account tags, since then cashflow wouldn't necessarily have a special meaning.

For external tools

Currently, hledger doesn't support calculating capital gains. But even if an external tool is to do so, it would be useful if one could do something like:

account Expenses:Tax:Property    ;  category:capex

Modifying in-built functions

Flags like --yearly and --quarterly make assumptions as what constitutes a year/quarter. It may be desirable to be able to modify this.

[simonmichael]

@the-solipsist, I'm not sure if you noticed the link to Account Types above ? They should allow controlling the cashflow report in the way you described (cf "supporting something like:").

[simonmichael]

1817 has landed.