oresmd: ORE Studio Market Data URI

A market_datum holds three things:

• the instrument type, an enum of all 45 that ORE's parseMarketDatum reads, in ORE's order, followed by oresmd's own, which name series ORE has no market datum for and so have no ORE key: fx_vol_surface, the calibrated FX volatility surface;
• the ORE quote type, an enum of all 16, plus none for the ORE token NULL;
• a list of (field, value) pairs. field is an enum of the 61 fields that any ORE key carries, and surface_id, which only oresmd's own types use. A value is one of five kinds: text, an ORE period or date, a decimal, a strike, or an enum code.

Equality compares every member, so a series and a quote are never equal. Free-text values, such as a ticker, a reference entity or a curve id, keep the case ORE wrote.

The schema has one row per instrument type. A row lists the type's fields in key order. For each field it states two facts:

• the role: identity when the field names the series, coordinate when it names a point in the series;
• whether the field may be none: an ORE key may leave the token out, as a CDS key may leave out its doc clause. The datum then holds an explicit none. A missing field never means a default.

A row also names its subject, the field the URI path holds, and its asset class. The asset classes are ir, fx, credit, equity, commodity, inflation, security, correlation, rating, shape_profile and generic.

The only constructor, market_datum::make, checks a datum against its row. It refuses an unknown field, a repeated field, a missing required field and a value of the wrong kind. So a datum that exists is valid, and code that reads it can rely on its row. A traits map gives each field its value type, so get<field::expiry>() is typed at compile time.

A series is a datum without its coordinate fields. series_of(d) drops them, and market_datum::make_series builds one directly. Two quotes on the same CDS curve differ only in term, so they share one series.

The coordinate fields of a series are its axes. A series with one axis is a term structure, which is the same thing as a curve. A series with two or more axes is a surface or a cube. The next section states this in full.

A market_index holds an index family, a subject and the family's fields. The families are the ones ORE's parseIndex reads:

market_index::make checks the fields against the family's row in the same way as a datum.

ore_key_codec::read follows ORE's marketdatumparser.cpp form by form. It accepts each key form ORE accepts, and it puts each token in the field ORE puts it in. It chooses a field by what a token is, such as a period, a date, a number, C or P, or ATM, not by its position. Each form cites the ORE form it reads. Code that differs per instrument type is a switch on the type, with one translation unit per asset class. The build treats a missing case as an error, so a new type cannot be forgotten.

ore_key_codec::write is the inverse. write(read(k)) is k, with one exception: a key that spells its type or quote type with an alias ORE also reads is written in the canonical spelling. The aliases are FX_SPOT for FX, FX_FWD for FXFWD and RATE_GVOL for RATE_LNVOL. The import reports each key it stores under another spelling.

The codec refuses two kinds of key that ORE accepts, because a datum could not write them back:

• a key with tokens ORE ignores, such as a trailing token after a cap/floor shift, or a sixth token on a base correlation tranche;
• a numeric slot that holds text ORE's std::stod reads only in part.

ore_index_codec::read follows ORE's parseIndex. It tries the families in ORE's order, and it splits the name into the fields ORE's parser reads. It accepts a name by its structure, as ORE does when a convention file defines the name. So CZK-CZEONIA reads with no list of index names.

ore_index_codec::write is the inverse. write(read(n)) is n, with one exception: ORE's spaced inflation aliases, such as UK RPI, are written without the space, as UKRPI.

The codec refuses a name that ORE completes from outside the name, because the index could not write it back:

• an empty name after EQ-, BOND- or COMM-;
• a power index with no delivery date, which ORE takes from the evaluation date;
• a power index with a DST flag, which ORE's own catalogue refuses too.

oresmd://<asset class>/<subject>?type=quote&instrument=<type>&quote=<quote type>&<field>=<value>...
oresmd://<asset class>/<subject>?type=series&instrument=<type>&quote=<quote type>&<field>=<value>...
oresmd://<asset class>/<subject>?type=fixing&index=<family>&<field>=<value>...

• The authority is the row's asset class.
• The path is the row's subject field, percent-encoded with its case kept. The query does not repeat it.
• The query starts with type. For a quote or a series, instrument and quote follow, as the ORE instrument and quote types in lower case. For a fixing, index follows, as the family.
• Each other field follows under its schema name, in schema order, with the case of its value kept.
• A field that holds none is left out.

A URI has a real structure that a standard library parses; boost::urls parses any RFC 3986 URI, not only HTTP URLs. The instruments differ in shape from one asset class to the next. A positional grammar would need a variant per asset class, or a NONE placeholder in every position a class does not use. Query parameters name each field, so each row writes only the fields it has.

The reader takes only the writer's own spelling, so one datum has one URI, and stored URIs compare as text. For a quote, this is a rule of the grammar:

1. A type=quote URI names exactly one market datum.
2. Every required field of the type's schema row is present.
3. A field that may be none is present only when it holds a value.
4. No other key is present.
5. No default applies. No partial form and no requirement form exist.

The reader refuses each of these:

• a missing key for a field that may not be none;
• an unknown key, a repeated key or an empty value;
• a coordinate field in a series URI;
• any other spelling of a valid URI, such as a reordered query or a percent-encoded letter in the path.

The reader does not ask whether ORE can spell the datum. The URI is the datum's identity and an ORE key is a boundary format, so a quote whose type ORE has no token for, such as hazard_rate, is a datum like any other and has a URI. What ORE can name is the question of ORE import and export, at the edge where ORE XML is read and written.

A series URI follows the same rules, without the coordinate fields. A fixing URI follows them too, and the reader also requires that the index writes an ORE name.

A curve, a surface and a cube are not separate kinds of identifier. Each is a series, and the series URI is its name. This is the identity that Add proper curve support to ores.marketdata settled: a composite object is a market_series row, and the row is named by its oresmd_uri. The task Resolve a composite object from its typed identity states it and builds the lookup by the URI's parts.

• The identity fields of the instrument type's schema row name the object. They are in the series URI, in schema order.
• The coordinate fields of the row are the object's axes. They are not in the series URI. They are in the quote URI of each point.
• A point is a quote of the series, and its coordinate values are its position on the axes. The ordered values of each axis are the object's shape, and they are stored beside the series; see Storage and the export.
• The axes are the coordinate fields the codec already reads. There is no second vocabulary of axis names that could disagree with the grammar. The decision is recorded in the story named above.

A term structure, as the page Term Structure defines it, is a series with one axis whose values are tenors. A bootstrapped interest rate curve, described in Interest Rate Curves, is one such series. The index tenor of a floating-rate curve is the tenor identity field, and the points are the term values.

FX_SPOT/RATE/EUR/USD reads as the first row and writes back as FX/RATE/EUR/USD, its canonical spelling.

The series URI of a curve or surface is the series URI in the third column of the table above. The table in What the series URI is for each kind of object gives the axes of each.

UK RPI reads as UKRPI and gets the same URI.