                Date Last Revised: August 2003

This file documents the use of keys in the key-value pair system used by the GnuCash Application (both the engine, and non-engine, GUI pieces). 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-value.hpp'.

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.

List of existing values

[ A ] [ B ] [ C ] [ D ] [ E ] [ F ] [ G ] [ H ] [ J ] [ K ] [ L ]
[ M ] [ N ] [ O ] [ kvpP ] [ kvpQ ] [ kvpR ] [ S ] [ T ] [ U ] [ V ] [ W ]

A

B

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}
    XXX not used, should be UIFreqSpec stuff ..
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: Time64
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: Time64
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/notes
Type: string
Entities: Book
Use:  User-suplied notes for the book.  The user can set this to any value
      and change it at any time for any reason.

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

Name: /book/prev-acct
Type: GUID
Entities: Account
Use:  The GUID of the account that precedes 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 precedes this one, chronologically.
      Note that the close-date of the previous book should equal the open-date
      of this book.

Name: /book/title
Type: string
Entities: Book
Use:  A user-suplied title for the book.  The user can set this to any value
      and change it at any time for any reason.

C

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: /counter_formats/...
Type: string
Entities: Book
Use:  Holders for a bunch of counter formats for various types.  Used
      specifically in the business objects, to format a counter value
      into a (string) ID.  The counter name is the path that follows
      /counter_formats/, e.g. "/counter_formats/GncCustomer"

      These formats are printf-style format strings that contain exactly
      one format specifier for an int64 (optionally preceded or followed
      by arbitrary other strings).

D

E

F

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.

G

Name: /gains-source
Type: guid
Entities: Split
Use:  GUID of the split that is at the source of the cap gains recorded
      in this split.

Name: /gains-split
Type: guid
Entities: Split
Use:  GUID of the split that records the capital gains for this split.

Name: /gemini/
Type: kvp_glist
Entities: Account, Book
Use:  kvp bag holding frames that identify accounts or books
      that are copies of this account.

Name: /gemini/.*
Type: kvp_frame
Entities: Account, Book
Use:  bag value holds a frame that identifies a single copied account.
      Other copies would appear in other bag values.

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

Name: /gemini/<type>/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/<type>/date
Type: time64
Entities: Account, Book
Use:  date that the copy was created.

H

Name: /hbci/
Type: frame
Entities: 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
Entities: Account
Use: Bank code of HBCI account

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

Name: /hbci/trans-retrieval
Type: Time64
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

J

K

L

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: /lot-mgmt/next-id
Type: int64
Entities: Account
Use: The next unused lot id number, used to autogenerate
     a lot title.

Name: /lot-split/
Type: kvp_glist
Entities: Split
Use:  A bag of kvp frames holding identification of splits
      that were split off of this split.  Same style as the
      /gemini/, look there for additional doco's.

Name: /lot-split/<type>/peer_guid
Type: GUID
Entities: Split
Use:  The GUID of the peer split which was split from this split.

M

N

Name: /notes
Type: string
Entities: Account, Lot, Transaction
Use: A user-suplied 'Notes' text field.  The user can set this to
     any value and change it at any time for any reason.
     Accessors: xaccAccountGetNotes(), xaccAccountSetNotes(),
     xaccTransGetNotes(), xaccTransSetNotes()

O

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: online-id
Type: string
Entities: All
Use: This holds a unique identifier for accounts, transactions and splits
     created by the generic import layer.  This allows imports of
     successive statements to automatically match accounts and transactions
     which have already been imported.

     This used to be set on transactions but not splits.  It is now set on
     splits but not transactions.  It is still checked on transactions, but
     this may change at some point in the future.

\subsection kvpP P

\subsection kvpQ Q

\subsection kvpR R

\verbatim
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.)

S

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.

T

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: /title
Type: string
Entities: Lot
Use:  A user-supplied title for the lot.  The user can set this to
      any value and change it at any time for any reason.

Name: trans-date-due
Type: Time64
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)

U

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.

V

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