; can be found in the same repository as this README.md file under the

; filename CC0-1.0.txt.  If this document has been separated from the

; repository, a [copy of CC0-1.0 can be found on Creative Commons' website at

; http://creativecommons.org/publicdomain/zero/1.0/legalcode

; ################################# TAGS ################################

; The Statement, Receipt, and Invoice tags' values should always a be a

; relative path names.  Note that we "check", but do not "assert" that the

; file name match a standard Unix-like path syntax, without spaces in the

; file name.

tag Statement

    assert value =~ /[^\/].+/

    check value =~ /[^\/][^ ]+(\/[^ ])+/

tag Receipt

    assert value =~ /[^\/].+/

    check value =~ /[^\/][^ ]+(\/[^ ])+/

tag Invoice

    assert value =~ /[^\/].+/

    check value =~ /[^\/][^ ]+(\/[^ ])+/

; IncomeType refers to the types of income a non-profit can receive.  In this

; example, it's for the categorizations on the USA Form 990.  This could be

; changed to accomodate other jurisdictions around the world.

tag IncomeType

    assert value =~ /^(Donations|RBI|UBTI)$/

; Program tag must match the general format of a ledger account as an

; assertion, but we at least check known names of programs, so that warnings

; are produced if a new program never seen before is encountered.

tag Program

    assert value =~ /[ A-z0-9\-]+(:[ A-z0-9\-]+)*/

    check  value =~ /^(Main Org:(Overhead|Direct Fundraising))$/

; Entity tag is just a string, but shouldn't have spaces, just letters,

; numbers and dashes.

tag Entity

    assert value =~ /[ A-z0-9\-]+(:[ A-z0-9\-]+)*/

tag TaxImplication

### Information Tags

In contrast to documentation tags, information tags can more traditionally be

considered pure "meta-data" for a ledger entry.

#### Entity Tag

The `Entity:` tag is required for many types of ledger entries.  The value of

the `Entity:` tag is a unique moniker that identifies the organization,

company, person, or legal entity that is the external party for the

transaction.

Note that there is no database of these monikers, so typos can cause

trouble.  However, you could implement checks in

`accounts/config/config-tags.ledger` using a regular expression to verify no

typos have occurred.  This would be somewhat cumbersome, since Ledger CLI

would likely require that the monikers be encoded into a regular expression.

Barring that, the

[integrity of your data should be periodically checked](checking-integrity-of-tag).

#### IncomeType Tag

The `IncomeType:` tag is used for all `Income:` accounts.  This refers to the

type of income.  The value of the `IncomeType:` tag is always a string.

Since this particular system is designed for USA non-profit entities who file

USA Form 990, the following `IncomeType` values are supported:

* `Donations`, which refers to standard charitable donations.

* `RBI`, which refers to "related business income".

* `UBTI`, which refers to "unrelated business taxable income.

Not that donor-advised funds and government grants don't currently have their

own `IncomeType`.  It's possible this might be necessary; the authors aren't

familiar with how to handle those items on the Form 990.  It would be a

relatively simple change to `config-tags.ledger`, though, to support other

income types, or to change it entirely to handle use-cases other than USA

Form 990 filing.

#### TaxImplication Tag

The `TaxImplication:` tag is used for all `Asset:` accounts when the

transaction includes a payment of $10.00 or more leaving the account.  This

tag catalogs any tax implications that might occur on outgoing funds.

The most important USA-related issue tracked by this tag are contractors who

go along with a TaxImplication tag.

The possible values for this field are:

* `1099`, indicating the amount paid requires issuance of a USA Federal Form

  1099 for the `Entity` involved.

* `Accountant-Advises-No-1099`, indicating that the circumstances and rules

  seem to indicate a USA Federal Form 1099 should be issued for the `Entity`

  involved, but an outside accountant advised that no 1099 need be issues for

  this `Entity`.

* `Bank-Transfer`, indicating that the amount is a transfer between two

  banking accounts under the control of the NPO itself.

* `Foreign-Individual-Contractor`, indicating that the NPO has established

  that the `Entity` is a contractor residing outside the USA who is not a USA

  citizen and does not for any reason pay taxes in the USA.

* `Foreign-Corporation`, indicating that the NPO has established

  that the `Entity` is a corporation outside the USA.

* `USA-Corporation`, indicating that the NPO has established that the

  `Entity` is an incorporated entity the USA (i.e., "Inc."), and therefore no

  1099 is required.

* `USA-501c3`, , indicating that the NPO has established that the `Entity`

  has federal 501(c)(3) status in the USA, and therefore no 1099 is required.

* `Refund`, indicating that the amount is a refund owed to the `Entity` from

  an amount previously paid to the NPO.

* `Reimbursement`, indicating that the amount is a reimbursement of expenses

  incurred by the `Entity` and thus it is not income to the `Entity`.

* `Tax-Payment`, indicating this is a tax payment to a taxing authority (such

  as the state or federal government) (e.g., a unrelated business income tax

  payment).

* `USA-LLC-No-1099`, indicating that the `Entity` is an LLC, but not the type

  of LLC for which the USA requires issuing a 1099.

* `Loan`, indicating that the `Entity` is receiving these funds as a Loan

  that is expected to be paid back.

#### Program Tag

The `Program` tag is used primarily to track program activity for `Income:`

and `Expense:` accounts.  This allows for knowing what particular initiative

initiated the income (e.g., a specific fundraising campaign) and/or what

particular program activity an expense is toward (e.g., funding travel to

some specific conference).

The Program tag is always a string with the same format as a Ledger CLI

account (primarily for use with Ledger CLI's `--pivot` and `--group-by`,