AllocData

An open data model for financial applications, typically those used by the do-it-yourself investor.

Available as an open source Swift library to be incorporated in other apps.

AllocData is part of the OpenAlloc family of open source Swift software tools.

Entities

The following entities are defined in the AllocData data model.

MAccount

This is the openalloc/account schema.

Each row of the Accounts table describes a unique account.

Name	Type	IsRequired	IsKey	Descript
accountID	string	true	true	The account number of the account.
title	string	false	false	The title of the account.
isTaxable	bool	false	false	Is the account taxable? (default: false)
canTrade	bool	false	false	Can you trade securities in the account? (default: false)
accountStrategyID	string	false	false	The strategy associated with this account, if any.

MAllocation

This is the openalloc/allocation schema.

Each row of the Allocations table describes a ‘slice’ of a strategy’s allocation pie.

Name	Type	IsRequired	IsKey	Descript
allocationStrategyID	string	true	true	The strategy associated with this allocation.
allocationAssetID	string	true	true	The asset of the allocation.
targetPct	double	false	false	The fraction of the asset in the strategy.
isLocked	bool	false	false	Whether the targetPct is locked (or floating).

MAsset

This is the openalloc/asset schema.

Each row of the Assets table describes a unique asset class.

It also establishes relations between assets.

Name	Type	IsRequired	IsKey	Descript
assetID	string	true	true	The identifier of the asset. (e.g., ‘Bond’)
title	string	false	false	The title of the asset.
colorCode	int	false	false	The code for the asset’s color palette.
parentAssetID	string	false	false	The id of the parent of the asset.

MCap

This is the openalloc/cap schema.

This table describes limits on allocation for an asset class within an account.

Name	Type	IsRequired	IsKey	Descript
capAccountID	string	true	true	The account in which the limit will be imposed.
capAssetID	string	true	true	The asset in which the limit will be imposed.
limitPct	double	false	false	Allocate no more than this fraction of the account’s capacity to the asset.

MHolding

This is the openalloc/holding schema.

A table where each row describes an individual position, with account, ticker, share count, share basis, etc.

Name	Type	IsRequired	IsKey	Descript
holdingAccountID	string	true	true	The account hosting the position.
holdingSecurityID	string	true	true	The security of the position.
holdingLotID	string	true	true	The lot of the position, if any.
shareCount	double	false	true	The number of shares held in the position.
shareBasis	double	false	true	The price paid per share of the security.
acquiredAt	date	false	true	The date of the acquisition.

MSecurity

This is the openalloc/security schema.

Table where each row describes a unique security, with its ticker, asset class and latest price.

Name	Type	IsRequired	IsKey	Descript
securityID	string	true	true	The symbol/securityID of the security.
securityAssetID	string	false	false	The asset class of the security.
sharePrice	double	false	false	The reported price of one share of the security.
updatedAt	date	false	false	The timestamp of the the reported price.
securityTrackerID	string	false	false	The index the security is tracking.

MStrategy

This is the openalloc/strategy schema.

Each row of the Strategies table describes a single allocation strategy.

Name	Type	IsRequired	IsKey	Descript
strategyID	string	true	true	The identifier of the strategy.
title	string	false	false	The title of the strategy.

MTracker

This is the openalloc/tracker schema.

Each row of the Tracker table describes a many-to-many relationship between Securities.

Name	Type	IsRequired	IsKey	Descript
trackerID	string	true	true	The identifier of the tracking index.
title	string	false	false	The title of the tracking index.

MTransaction

This is the openalloc/transaction schema.

A table of recent transaction history, including purchases, sales, and other actions.

NOTE: this replaces the deprecated ‘MHistory’ entity.

Name	Type	IsRequired	IsKey	Descript
txnAction	string	true	true	The code of the type of transaction (see below).
txnTransactedAt	date	true	true	The date of the transaction.
txnAccountID	string	true	true	The account in which the transaction occurred.
txnSecurityID	string	true	true	The security involved in the transaction.
txnLotID	string	true	true	The lot of the position involved in the transaction (blank if none).
txnShareCount	double	true	true	The number of shares transacted.
txnSharePrice	double	false	false	The price at which the share(s) transacted. (0 if none provided).
realizedGainShort	double	false	false	The total short-term realized gain (or loss) from a sale.
realizedGainLong	double	false	false	The total long-term realized gain (or loss) from a sale.

Note that brokerage exports may omit share price on security transfers.

The action types:

Type	ShareCount	SharePrice	SecurityID	Descript
buysell	<0 if sale; >0 if purchase	>0, price/share	required	Purchase/sale of security to/from cash.
income	amount of income	1.0 (cash)	if dividend	Income from interest, or the dividend of a stock/ETF/etc..
transfer	<0 is outgoing; >0 is incoming	1.0 if cash; >0 for security; nil if none provided	if not cash	Transfer of security/cash to/from external source.
miscflow	<0 is outgoing; >0 is incoming	1.0 (cash)	ignored	Neutral (non-income) cashflow to/from account.

MRebalanceAllocation

This is the openalloc/rebalance/allocation schema.

Each row of the RebalanceAllocation table describes an allocation that drives a rebalance.

Name	Type	IsRequired	IsKey	Descript
allocationAccountID	string	true	true	The account to which the asset is allocated.
allocationAssetID	string	true	true	The asset class of the allocation.
amount	double	true	false	The amount in dollars allocated.

MRebalancePurchase

This is the openalloc/rebalance/purchase schema.

Each row of the RebalancePurchase table describes an acquisition of a position to satisfy a rebalance.

Name	Type	IsRequired	IsKey	Descript
purchaseAccountID	string	true	true	The account to host the position.
purchaseAssetID	string	true	true	The asset class of the position to acquire.
amount	double	true	false	The amount in dollars to acquire.

MRebalanceSale

This is the openalloc/rebalance/sale schema.

Each row of the RebalanceSale table describes a liquidation of a position to satisfy a rebalance.

Name	Type	IsRequired	IsKey	Descript
saleAccountID	string	true	true	The account hosting the position.
saleSecurityID	string	true	true	The security of the position.
saleLotID	string	true	true	The lot of the position, if any.
amount	double	true	false	The amount in dollars to liquidate from this position.
shareCount	double	false	false	Estimated number of shares to liquidate from this position.
liquidateAll	bool	false	false	If true, the entire position can be liquidated.

MValuationSnapshot

This is the openalloc/valuation/snapshot schema.

Each row of the ValuationSnapshot table describes a valuation captured at a particular time.

Name	Type	IsRequired	IsKey	Descript
valuationSnapshotID	string	true	true	The unique valuation snapshot identifier.
capturedAt	date	true	false	The timestamp when the snapshot was created.

MValuationPosition

This is the openalloc/valuation/position schema.

Each row of the valuation position table describes a position captured at a particular time for a valuation snapshot. It can represent multiple holdings of an account for an asset class.

Name	Type	IsRequired	IsKey	Descript
valuationPositionSnapshotID	string	true	true	The valuation snapshot ID for the position.
valuationPositionAccountID	string	true	true	The account hosting the position.
valuationPositionAssetID	string	true	true	The asset class of the position.
totalBasis	double	true	false	The price paid to establish position.
marketValue	double	true	false	The market value of the position.

MValuationCashflow

This is the openalloc/valuation/cashflow schema.

Each row of the valuation cashflow table describes a cash flow at a particular time. It is not explicitly bound to any valuation snapshot. Typically, multiple history items are rolled up into a cash flow item.

Name	Type	IsRequired	IsKey	Descript
valuationCashflowTransactedAt	date	true	true	The timestamp when this flow occurred.
valuationCashflowAccountID	string	true	true	The account in which the flow occurred.
valuationCashflowAssetID	string	true	true	The asset class flowed.
amount	double	true	false	The amount of the flow (-outgoing, +incoming).

MSourceMeta

This is the openalloc/meta/source schema.

Each row of the SourceMeta table describes an import or transformation of source data. It can also include extracted data, such as the published export date found within.

Name	Type	IsRequired	IsKey	Descript
sourceMetaID	string	true	true	The unique ID of the source meta record.
url	string	false	false	The source URL, if any.
importerID	string	false	false	The id of the importer/transformer, if any.
exportedAt	date	false	false	The published export date of the source data, if any.

Data Formats

Dates

In delimited text files, the dates should be in the ISO 8601 / RFC 3339 format (e.g., “2012-12-31T19:00:00Z”).

API

Entities in the data model all conform to the following protocols:

Base

Base functionality for all entities. Currently just a schema identifier.

public protocol AllocBase {
    static var schema: AllocSchema { get }
}

Keyed

Used to retrieve and generate the entity’s primary key.

This new struct-based implementation replaces the old string-based one.

The emptyKey property can be used for picker tag values, as an example.

public protocol AllocKeyed: Hashable {
    associatedtype Key: Hashable, Codable

    var primaryKey: Key { get }
    static var emptyKey: Key { get }
}

The entities also conform to the Identifiable protocol where the id is the primary key.

Rowed

Used to parse (decode) and generate (encode) delimited data for the entities.

public protocol AllocRowed: AllocKeyed {
    // pre-decoded row, without strong typing
    typealias RawRow = [String: String]

    // decoded row, with stronger typing
    typealias DecodedRow = [String: AnyHashable]

    // create object from row
    init(from row: DecodedRow) throws

    static func decode(_ rawRows: [RawRow], rejectedRows: inout [RawRow]) throws -> [DecodedRow]

    // additive update from row
    mutating func update(from row: DecodedRow) throws

    static func getPrimaryKey(_ row: DecodedRow) throws -> Key
}

Attributable

Used to fetch a description of the entity’s attributes.

public protocol AllocAttributable {
    static var attributes: [AllocAttribute] { get }
}

Contributing

Contributions are welcome. You are encouraged to submit pull requests to fix bugs, improve documentation, or offer new features.

The pull request need not be a production-ready feature or fix. It can be a draft of proposed changes, or simply a test to show that expected behavior is buggy. Discussion on the pull request can proceed from there.

Contributions should ultimately have adequate test coverage. See tests for current entities to see what coverage is expected.