gnucash/src/engine/kvp_doc.txt

                    kvp_doc.txt
                    -----------

This file documents the use of keys in the key-value pair system
used by the Engine. Before assigning keys for use, please read
the Key-Value Policy in the GnuCash Design Document located
under src/doc/design.

The format of the data below is:

Name: The name of the key, including key names of parent frames
      with the parent frames listed first, as in a fully-qualified
      filename. Use the '/' character to separate keys.

Type: The type of value stored in the key. The types are listed in
      'kvp_frame.h'.

Entities: Which engine entities (Accounts, Transactions, Splits)
          can use this key. Use 'All' if every entity could have
          the key.

Use: The use to which the key will be put. Include any requirements
     for using the key here. Also include any API calls which use
     the key. If more than one entity can use the key, 


Example:

Name: my-favorite-thing
Type: string
Entities: Account
Use:  xaccGetMyFavoriteThing(), xaccSetMyFavoriteThing()
      This key stores a text description of the user's
      favorite thing. Do not use this key to store things
      which the user merely likes!


Please put the keys in alphabetical order.

--------------------------------------------------------------------------

Name: from-sched-xaction
Type: GUID
Entities: Transaction
Use: Identifies that the Transaction was created from a ScheduledTransaction,
     and stores the GUID of that SX.

-----------------------

Name: /gemini/
Type: kvp_frame
Entities: Account, Book
Use:  kvp subdirectory holding identification of accounts or books 
      that are copies of this account.

Name: /gemini/ncopies
Type: int64
Entities: Account, Book
Use:  number of subdirectories containing copy info.

Name: /gemini/0/
Type: kvp_frame
Entities: Account, Book
Use:  subdirectory holding identification of the first copied account.
      Other copies would appear in directories /gemini/1/, /gemini/2/,
      etc.

Name: /gemini/0/acct_guid
Type: guid
Entities: Account
Use:  guid of another account that is a copy of this one.

Name: /gemini/0/book_guid
Type: guid
Entities: Account, Book
Use:  When this appears in an account, then it contains the guid of 
      the book that the other account belongs to.  When this appears
      in a book, then this is the guid of the other book.

Name: /gemini/0/date
Type: timespec
Entities: Account, Book
Use:  date that the copy was created.

-----------------------

Name: last-num
Type: string
Entities: Account
Use: xaccAccountGetLastNum, xaccAccountSetLastNum
     Store the last number used in an account's transactions.
     Used in auto-filling the Num field.

Name: memo
Type: string
Entities: Split
Use: xaccSplitGetMemo, xaccSplitSetMemo
     Store the 'Memo' string associated with Splits.

Name: notes
Type: string
Entities: Account, Transaction
Use: xaccAccountGetNotes, xaccAccountSetNotes,
     xaccTransGetNotes, xaccTransSetNotes
     Store the 'Notes' string which was previously stored in
     the Account structure directly.

Name: old-currency
Type: string
Entities: Account
Use: This string holds the canonical name of the old Account
     currency. This may be deleted at some point in the future.

Name: old-currency-scu
Type: gint64
Entities: Account
Use: This holds the old currency scu. This may be deleted at
     some point in the future.

Name: old-docref
Type: string
Entities: Transactions, Splits
Use: This string holds the old Docref value which was supported in earlier
     versions of GnuCash but which was never used for any purpose. The
     value is retained in case any users were making use of it.

Name: old-price-source
Type: string
Entities: Account
Use: This string holds the old Price Source code used by earlier versions
     of GnuCash and stored in the obsolete AccInfo structure. The use of
     this value will be deprecated when the new version of Finance::Quote
     is fully supported. The new version of Finance::Quote uses a different
     scheme to identify sources for price quotes.

Name: old-security
Type: string
Entities: Account
Use: This string holds the canonical name of the old Account
     security. This may be deleted at some point in the future.

Name: old-security-scu
Type: gint64
Entities: Account
Use: This holds the old security scu. This may be deleted at
     some point in the future.

Name: reconcile-info
Type: frame
Entities: Account
Use: store reconcile information about accounts

Name: reconcile-info/include-children
Type: gint64
Entities: Account
Use: A boolean flag indicating whether transactions in sub-accounts should be
     included during reconcilition.

Name: reconcile-info/last-date
Type: frame
Entities: Account
Use: store the statement date of the last reconciliation

Name: reconcile-info/postpone/date
Type: gint64
Entities: Account
Use: store the ending statement date of a postponed reconciliation

Name: reconcile-info/postpone/balance
Type: numeric
Entities: Account
Use: store the ending balance of a postponed reconciliation

Name: reconcile-info/auto-interest-transfer
Type: string
Entities: Account
Use: allows the user to override the global reconcile option
     "Automatic interest transfer" on a per-account basis.
     Acceptable values are "true" and "false".
     (This really could use a KVP_TYPE_BOOLEAN.)

Name: /sched-xaction/
Type: frame
Entities: Split in a SchedXaction
Use: Storage for the various fields of a scheduled transaction's
     template Splits.

Name: /sched-xaction/account
Type: GUID
Entities: Split associated with a SchedXaction
Use: The GUID of this Split's xfrm account.

Name: /sched-xaction/credit-formula
Type: string
Entities: Split associated with a SchedXaction
Use: Store the formula for the credit side of the split

Name: /sched-xaction/debit-formula
Type: string
Entities: Split associated with a SchedXaction
Use: Formula for the debit.  Either the credit or the 
debit formula must be empty.
Name: split-type
Entities: Split
Use: xaccSplitGetType, xaccSplitMakeStockSplit
     Store a string representing the type of split, if not normal.

Name: /tax-US/code
Type: string
Entities: Account
Use: see src/scm/report/[tax,txf]*.scm

Name: /tax-US/payer-name-source
Type: string
Entities: Account
Use: see src/scm/report/[tax,txf]*.scm

Name: tax-related
Type: gint64
Entities: Account
Use: A boolean flag indicated whether the Account is tax-related.

Name: trans-date-due
Type: Timespec
Entities: Transaction
Use: Accounts/Receivable, Accounts/Payable Due Date.

Name: trans-txn-type
Type: string
Entities: Transaction
Use: A/R, A/P Transaction Type (Invoice or Payment)

Name: user-keys
Type: frame
Entities: All
Use: This frame is used to store keys which are editable directly by
     the user. The program should not attach any semantics to keys
     under this frame.

Name: void-reason
Type: string
Entities: Transaction
Use: This string is used to store the reason why a transaction has been 
voided.  Note that it should only exist if the transaction has been voided.

Name: void-former-amount
Type: gnc_numeric
Entities: Split
Use: To store the amount of the this split before it was voided.  Note
that it should only exist if the parent transaction has been voided (but
checking the reconcile status of the split is a more direct way of finding
out a split has been voided).

--------------------------- end of document ------------------------