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: /book/
Type: kvp_frame
Entities: Account, Book, Transaction
Use:  kvp subdirectory holding info relating to accounting periods, including
      the 'twin' of an open/closed account, pointers to the open-balance
      transactions, the closing dates, etc.

Name: /book/accounting-period
Type: string, enum {none, week, month, quarter, trimester, year}
Entities: Book
Use:  An enumerated identifier indicating how often books are supposed
      to be closed.  This key will typically be present only in an
      open book, as it seems meaningless in a closed book.

Name: /book/close-date
Type: Timespec
Entities: Book
Use:  The posted closing date of this book.  This book only contains 
      transactions whose posted date is earlier than this closing date.

Name: /book/closed-acct
Type: GUID
Entities: Transaction
Use:  The GUID of the account for which this transaction represents the 
      opening balance.  This value will occur *only* in transactions that
      are opening balances.

Name: /book/closed-book
Type: GUID
Entities: Transaction
Use:  The GUID of the book for which this transaction represents the 
      opening balance.  This value will occur *only* in transactions that
      are opening balances.

Name: /book/log-date
Type: Timespec
Entities: Book
Use:  A log of the date which the user performed the closing of the book.

Name: /book/next-acct
Type: GUID
Entities: Account
Use:  The GUID of the account that follows this one, chronologically.
      Note that the open-date of the next book should equal the close-date
      of the book that this account belongs to.

Name: /book/next-book
Type: GUID
Entities: Account, Book
Use:  The GUID of the book that follows this one, chronologically.
      Note that the open-date of the next book should equal the close-date
      of this book.

Name: /book/open-date
Type: Timespec
Entities: Book
Use:  The posted opening date of this book.  This book only contains transactions
      whose posted date is laterr than this closing date.

Name: /book/prev-acct
Type: GUID
Entities: Account
Use:  The GUID of the account that preceeds this one, chronologically.
      Note that the close-date of the previous book should equal the open-date
      of the book that this account belongs to.

Name: /book/prev-book
Type: GUID
Entities: Account, Book
Use:  The GUID of the book that preceeds this one, chronologically.
      Note that the close-date of the previous book should equal the open-date
      of this book.

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

Name: /counters/...
Type: int64
Entities: Book
Use:  Holders for a bunch of counters for various types.  Used specifically
      in the business objects for ID counters.  The counter name is the path
      that follows /counters/, e.g. "/counters/GncCustomer"
      

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

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: /hbci/
Type: frame
Entitites: Account, Book
Use: subdirectory for information related to the German online banking
protocol HBCI

Name: /hbci/account-id
Type: string
Entities: Account
Use: HBCI Account code of the HBCI counterpart of this gnucash account
in the real world

Name: /hbci/bank-code
Type: string
Entitites: Account
Use: Bank code of HBCI account

Name: /hbci/country-code
Type: gint64
Entitites: Account
Use: Country code of the bank of HBCI account

Name: /hbci/trans-retrieval
Type: Timespec
Entities: Account
Use: Time of the last statement retrieval through HBCI for this
specific account

Name: /hbci/config-filename
Type: string
Entitied: Book
Use: OpenHBCI configuration file name, where the real HBCI
configuration for the OpenHBCI library can be found 

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

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: /lot-mgmt/
Type: kvp_frame
Entities: Account
Use: Frame holding info regarding how lots should be managed in this
     account, including what accounting policy to use, where realized
     gains should be reported, and etc. 

Name: /lot-mgmt/gains-acct/
Type: frame
Entities: Account
Use: When a lot in this account is double-balanced, this frame 
     holds per-currency accounts to which realized gains are to 
     be posted.

Name: /lot-mgmt/gains-acct/xxxxx
Type: guid
Entities: Account
Use: When a lot in this account is double-balanced, this key specifies
     the account to which realized gains are to be posted.


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

Name: notes
Type: string
Entities: Account, Lot, Transaction
Use: xaccAccountGetNotes(), xaccAccountSetNotes(),
     xaccTransGetNotes(), xaccTransSetNotes(),
     gnc_lot_get_notes(), gnc_lot_set_notes()
     Store the 'Notes' string.

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 ------------------------