Protocol buffer schemas shared by KBVE services, games and sites.
Last changed in19476db91on
syntax = "proto3";
package kbve.market.v1;
import "google/protobuf/timestamp.proto";
import "kbve/asset/v1/asset.proto";
import "kbve/common/v1/decimal.proto";
// What a company earns, and what it pays out.
//
// Facts about a company, filed under market rather than asset because every
// figure that a screen actually sorts on is a ratio with a price on one side.
// They go stale as a set, on a date, which is market-data behaviour.
// The period a set of figures covers.
enum FiscalPeriod {
FISCAL_PERIOD_UNSPECIFIED = 0;
FISCAL_PERIOD_Q1 = 1;
FISCAL_PERIOD_Q2 = 2;
FISCAL_PERIOD_Q3 = 3;
FISCAL_PERIOD_Q4 = 4;
FISCAL_PERIOD_FULL_YEAR = 5;
// The last four quarters, whatever they are. Not a reported period: a
// rolling window computed from four that were.
FISCAL_PERIOD_TRAILING_TWELVE_MONTHS = 6;
}
// Whether a set of figures is what the company said or what the market thinks.
enum FigureBasis {
FIGURE_BASIS_UNSPECIFIED = 0;
// As filed.
FIGURE_BASIS_REPORTED = 1;
// Analyst consensus, before the fact.
FIGURE_BASIS_ESTIMATE = 2;
// Restated after the fact. A revision is not a correction of a data feed;
// it is the company changing its own answer, and a series that silently
// replaces the original loses the fact that it moved.
FIGURE_BASIS_RESTATED = 3;
}
// One reporting period.
message EarningsReport {
kbve.asset.v1.AssetRef ref = 1;
FiscalPeriod period = 2;
// The fiscal year the period belongs to, which is not always the calendar
// year it ends in.
int32 fiscal_year = 3;
FigureBasis basis = 4;
// When the period ended, and when the company said so. The gap between them
// is weeks, and a figure filed under the wrong one lands in the wrong
// quarter.
google.protobuf.Timestamp period_end = 5;
optional google.protobuf.Timestamp reported_at = 6;
// What the figures are denominated in. A foreign listing reports in its own
// currency and a ratio that mixes it with a price in another is nonsense.
string currency = 7;
optional kbve.common.v1.Decimal revenue = 8;
optional kbve.common.v1.Decimal net_income = 9;
// Per share, diluted. Signed: a loss is a normal quarter, not a missing one.
optional kbve.common.v1.Decimal eps = 10;
optional kbve.common.v1.Decimal eps_estimate = 11;
optional kbve.common.v1.Decimal operating_income = 12;
optional kbve.common.v1.Decimal free_cash_flow = 13;
optional kbve.common.v1.Decimal total_assets = 14;
optional kbve.common.v1.Decimal total_debt = 15;
}
// What a company pays holders, and how reliably.
message DividendPolicy {
// Payments per year: 4 quarterly, 1 annual, 0 for a company that does not
// pay one.
optional int32 frequency = 1;
// Per share, per payment, in the currency below.
optional kbve.common.v1.Decimal amount_per_share = 2;
optional string currency = 3;
// Trailing twelve months of payments over the current price, in basis
// points. Derived, and stored because it depends on a price that moves: a
// yield quoted without saying when is a yield against an unknown price.
optional int32 yield_bps = 4;
optional google.protobuf.Timestamp yield_as_of = 5;
// Share of earnings paid out, in basis points. Above ten thousand means the
// company is paying more than it earns, which is the number this field
// exists to make visible.
optional int32 payout_ratio_bps = 6;
optional google.protobuf.Timestamp last_ex_date = 7;
optional google.protobuf.Timestamp next_ex_date = 8;
// Consecutive years of increases, which is the whole basis of the
// dividend-growth screens.
optional int32 growth_streak_years = 9;
}
// The derived figures a screen actually sorts on.
//
// Every one is a ratio with a price on one side, so the whole message is only
// meaningful with its as_of. Kept together rather than hung off Asset for that
// reason: they go stale as a set, at the same moment, and a consumer holding
// half of one snapshot and half of another is comparing two different days.
message Fundamentals {
kbve.asset.v1.AssetRef ref = 1;
google.protobuf.Timestamp as_of = 2;
string currency = 3;
// Price over trailing twelve-month earnings, in basis points to stay exact.
// Absent rather than negative for a company that lost money: a negative P/E
// sorts as the cheapest stock on the exchange, and it is the opposite.
optional int32 pe_ratio_bps = 4;
// Against forward estimates rather than reported earnings.
optional int32 forward_pe_bps = 5;
optional int32 price_to_book_bps = 6;
optional int32 price_to_sales_bps = 7;
optional kbve.common.v1.Decimal eps_ttm = 8;
optional kbve.common.v1.Decimal revenue_ttm = 9;
optional kbve.common.v1.Decimal book_value_per_share = 10;
// How far the price swings against the market, in basis points: 15000 is a
// beta of 1.5.
optional int32 beta_bps = 11;
optional kbve.common.v1.Decimal market_cap = 12;
optional kbve.common.v1.Decimal enterprise_value = 13;
optional DividendPolicy dividend = 14;
// When the company next reports. The single most useful date on a screen:
// it is when everything above stops being true.
optional google.protobuf.Timestamp next_earnings_at = 15;
// Whether that date is confirmed by the company or estimated from its
// history. An estimated date presented as confirmed is how a position gets
// held through an earnings print by accident.
optional bool next_earnings_confirmed = 16;
// Fraction of the float sold short, in basis points.
optional int32 short_interest_bps = 17;
// What a fund's holdings are actually worth per share, and when that was
// struck. Absent on anything that is not a fund.
//
// A fund has two prices: what it holds and what it trades for. For an ETF
// they stay within a few basis points because shares can be created against
// the basket; for a closed-end fund, or an ETF whose underlying market is
// shut while its own is open, they separate, and the gap is the entire
// decision. NAV is struck once a day, so it is stale against an intraday
// price by construction -- which is why it carries its own timestamp rather
// than sharing as_of above.
optional kbve.common.v1.Decimal nav = 18;
optional google.protobuf.Timestamp nav_as_of = 19;
// Price over NAV, in basis points, signed: 200 is a two percent premium,
// -1500 a fifteen percent discount. Stored because it is the figure the
// screens sort on and recomputing it against a later NAV answers a
// different question.
optional int32 premium_to_nav_bps = 20;
}