oresmd: ORE Studio Market Data URI

oresmd is a proposed, structured ORE-Studio-native market data identifier — a real RFC 3986 URI (oresmd://<asset_class>/<entity>?...), not a bespoke string format — designed to close every gap the gap analysis task found: no structured tenor field (so same-currency, different-tenor indices collide), no curve-role field (so discount and projection curves for the same currency can't be told apart), and no single field ORE Studio's own schemas key off that projects deterministically into ORE's index name, curve key, and quote key. Because its optional metadata (tenor, curve role, index family, …) lives in the URI's query string rather than fixed path positions, the same grammar covers every asset class — FX, interest rates, swaptions, equities, credit, commodities, inflation, correlation — without per-asset-class variants or NONE placeholders. It generalises the one place ORE Studio already gets this right (fx_spot_generation_config.ore_key) and supersedes the free-text qualifier in the existing market_series key by giving it a structured source to be deterministically generated from, rather than typed by hand.

Market Data Requirement draws a distinction between a logical requirement ("the EUR discount curve", stated independently of any particular instance that satisfies it) and the physical instance it resolves to (one concrete, bootstrapped curve object). Because oresmd's query parameters are already optional and conditional on asset class, the same URI can express both ends of that distinction — not two different schemes, but two different points on one specificity spectrum:

• A requirement is an oresmd URI with only the fields that requirement actually constrains — oresmd://ir/eur?role=discount names "the EUR discount curve" without yet committing to which benchmark index builds it or what kind of thing (fixing/curve/quote) is being asked for.
• A resolved instance is the same URI with every field its asset class expects filled in — oresmd://ir/eur?index=estr&tenor=1d&role=discount&type=curve names one concrete curve.

Resolving a requirement to an instance, in these terms, is filling in the fields the partial URI left unspecified — exactly the step Market Data Requirements and Resolution already describes in the abstract, given a concrete, structured shape here for the IR/curve-role case the gap analysis flagged, where today's free-text index_name gives it none. A requirement-level URI can still resolve to more than one instance-level URI over time (a different vintage, a different source) — resolution picks one, it does not collapse the distinction between the two levels.

oresmd://<asset_class>/<entity>[?<query>]

• asset_class (the URI's authority/host component, not a path segment — the // before it makes it so): one of ir, fx, equity, credit, commodity, inflation, correlation — matches the asset-class sections of External market data identifiers exactly, so every worked example in that document has a direct oresmd counterpart below. A boost::urls::url implementation reads this via .authority()=/.host()=, not .segments().
• entity (path, mandatory): the free-form subject — a currency (usd) for IR, a 6-character currency pair (eurusd) for FX, a ticker or index code (aapl, sp5) for equities, a reference-entity name (itraxx-europe, vod) for credit, a commodity code (gold, wti) for commodities, an inflation index code (ukrpi) for inflation, and a hyphen-separated factor pair (ccy-eur-usd) for correlation.
• Query parameters (all optional; each asset class documents which it uses):
  • ccy: settlement/quote currency, when distinct from entity (equities, credit, commodities — an FX pair already encodes both currencies in entity, and IR's entity already is the currency).
  • index: benchmark index family (libor, euribor, sofr, estr, sonia, tona, …) — IR only.
  • tenor: the index's own tenor (3m, 6m, 1d, …) — IR only.
  • role: curve role, one of discount, projection, self_discounting (the degenerate single-curve case current synthetic data uses, where one curve serves both roles) — IR only.
  • type: instrument type, one of fixing (a rate fixing/index), curve (a whole curve), quote (one raw quote/point), or vol (a volatility surface point) — used by every asset class.
  • quote: only meaningful when type=quote — the ORE quote TYPE (e.g. ir_swap, mm, cds, fwd), the first segment of ORE's TYPE/METRIC/... quote key. A per-asset-class enum, independent of the metric column: for an IR ir_swap the metric is RATE, for a basis_swap it is BASIS_SPREAD. Absent, it defaults to the asset class's canonical quote type (spot for FX/equity/commodity, cds for credit), and the projection yields no quote key where no default exists (IR and inflation, whose quote is required for a type=quote projection); correlation never uses it, since its only quote type is hardcoded CORRELATION/RATE.
  • metric: only meaningful when type=quote — disambiguates what kind of quote point refers to, since a coordinate on an IR curve is ambiguous between a par rate observed in the market (par_rate) and a directly-quoted discount factor sampled off the curve (discount_factor) — see below for why this is a separate field from tenor=/=point rather than folded into either. A per-asset-class enum (e.g. basis_spread, ratio, price, yield_spread); absent, it defaults from the quote type's own metric (an ir_swap defaults to rate, a basis_swap to basis_spread).
  • model: only meaningful when type=vol — the volatility model subtype, one of rate_lnvol, rate_nvol, rate_slnvol, shift, price. Defaults to rate_lnvol.
  • point: the term-structure or surface coordinate for a quote=/=vol URI (a swap tenor, a curve point, or a comma-separated surface coordinate like 5y,2y,atm — expiry, tenor, strike for type=vol) — absent for scalar quotes (FX spot, equity spot, correlation, recovery rate).

Every field is justified by a specific finding in the gap analysis — no speculative fields:

Deterministic, worked for each field combination:

• Index name (type=fixing): <entity>-<index>-<tenor> for indexed benchmarks (e.g. USD-LIBOR-3M); <entity>-<index> for overnight benchmarks with no tenor suffix (e.g. USD-SOFR, EUR-ESTR) — mirrors ORE's own index-name convention exactly.
• Curve key (type=curve): Yield/<entity>/<curve_id> where curve_id is <entity><tenor> with the tenor's unit letter and any separators stripped (e.g. USD3M, USD1D, EUR6M), per ORE's Yield/<CCY>/<CURVE_ID> convention.
• Quote key (type=quote or type=vol): per the ORE market data catalogue's documented per-type shapes — see the worked examples below, one per asset class, for the exact mapping each asset class uses. Not every dimension in every catalogue shape is derivable from an oresmd field alone: IR_SWAP/RATE's settlement/spot-lag dimension (2D in the worked USD/EUR examples below) is a per-currency market convention (2 business days for USD/EUR, but not universal), looked up from entity rather than carried by any oresmd query parameter — the same kind of external-convention lookup the Bloomberg/RIC projection below needs, just for a dimension internal to ORE's own quote key rather than an external vendor notation.
• Bloomberg/RIC (best-effort only, per the survey — these are vendor-licensed and not fully systematic): a lookup table keyed on (asset_class, entity, index, tenor) is required rather than a pure string transform, since — per External market data identifiers — neither vendor's convention is a deterministic function of these fields alone (e.g. RIC's ICAP=/=GFI broker suffixes, Bloomberg's per-asset-class ticker shape). The URI does not attempt to generate a valid RIC/Bloomberg string; it only records which one a given URI corresponds to, where known, the same reference-table approach external_market_data_identifiers.org's worked examples already use.

One per asset class, matching External market data identifiers's own worked instruments exactly, so every row in that comparison table has a direct oresmd counterpart here.

A structured URI is only half the design — code needs typed objects to build/parse/validate it against, not raw strings. The type system below keeps the same logical/physical distinction as the rest of this document at the type level, not just the value level: a ..._requirement type and a ..._identifier type exist per asset class, so a partially-specified requirement and a fully-resolved instance are never the same type — a function that needs a resolved instance simply cannot be called with a requirement, a compile-time guarantee the string-based oresmd URI alone cannot give.

Deliberately no abstract base class or virtual dispatch: one independent, strongly-typed, plain struct per asset class (fx_market_data_identifier, ir_market_data_identifier, equity_market_data_identifier, credit_market_data_identifier, commodity_market_data_identifier, inflation_market_data_identifier, correlation_market_data_identifier), each exposing only the fields that asset class actually uses (an fx_market_data_identifier has no index_family=/=tenor=/=curve_role members at all, rather than NONE-valued ones), mirroring the query-parameter grammar's own conditionality at the type level. Every identifier struct also carries a volatility_surface_point (expiry, strike, volatility_model_subtype, the model whose surface the point samples) for type=vol instruments, though only swaption vol projects a vol quote key today. The seven identifier structs are tied together only as a std::variant<...> (aliased market_data_identifier for readability), never as siblings of a common base — since the URI's asset_class authority component already tells a consumer which concrete struct it is looking at, a base class/virtual interface would buy nothing an ordinary tagged union does not already provide, and it would come at a real cost: reflection-based serialisation libraries (e.g. rfl=/reflect-cpp, a natural fit for round-tripping these plain structs to/from JSON or the database) generally handle plain structs and =std::variant well but do not handle polymorphic class hierarchies gracefully. Three free functions do the asset-class dispatch instead of a virtual call: parse_oresmd(uri) -> market_data_identifier inspects the URI's asset_class component and constructs the matching concrete struct inside the variant; to_uri(market_data_identifier) -> oresmd_uri does the reverse via std::visit; resolve(market_data_requirement, ...) -> market_data_identifier takes a requirement plus whatever additional information narrows it (a source, a vintage, an explicit choice among the fields still open) and, via std::visit over the requirement variant, either produces the matching identifier variant member or fails if fields remain unresolved.

• A parallel market_data_requirement variant (same seven asset classes, same "no base class" shape) mirrors the identifier variant field-for-field. Note that "resolved" does not mean "every field on the identifier class is non-null" — the swaption worked example above is a fully-resolved ir_market_data_identifier with index=/=tenor=/=role all absent, because those fields simply do not apply to a type=vol instrument. index=/=tenor=/=role=/ =metric=/=point are therefore std::optional on both the identifier and the requirement — the fields that differ are which of them resolve(...) is obliged to have settled (one way or the other, including "confirmed not applicable") before it will produce an identifier at all, a check that varies by type (a curve needs index=/=tenor=/=role settled; a vol URI does not). Only ccy and type are unconditionally mandatory on ir_market_data_identifier, since every IR instrument has both.
• Controlled vocabularies (asset_class, instrument_type, curve_role, metric, and — closing the same free-text gap index_name has today — index_family) are enums, not strings, so an invalid value is a compile error or a construction-time validation failure, not a silently-accepted typo.
• tenor, currency, and point are not reinvented here — a real implementation would bind these to whatever this codebase's own domain types for tenor and currency already are, rather than introduce competing ones; credit and commodity reuse the same generic point type IR's swap-tenor/curve-point case uses (carrying seniority+tenor for credit, or a forward tenor for commodity), exactly mirroring how their URI-level point query key already absorbs those dimensions rather than getting dedicated fields of their own.

Source: market_data_urn_types.puml. Regenerate with plantuml -tpng doc/knowledge/domain/market_data_urn_types.puml.

oresmd is designed as ORE Studio's single identifier scheme, not one more scheme coexisting alongside fx_spot_generation_config.ore_key, market_series's free-text qualifier, and ir_curve_generation_config's (currency_code, index_name) pair — those are all superseded, not wrapped. The per-field migration plan (what each legacy field maps to, and what gets deleted once migration is complete) is tracked as follow-on implementation work in Migrate to oresmd, delete market_series qualifier and ore_key, rather than in this design document.

• Gap analysis: ORE Studio identifiers vs ORE's real addressing scheme — the gap table every field above is justified against.
• Survey ORE, Bloomberg, and Reuters market data notations and External market data identifiers — the survey material the projection rules (especially the Bloomberg/RIC best-effort mapping) are grounded in, and the worked instruments this document's examples are matched to.
• ORE market data catalogue — the authoritative per-type quote-key shapes the quote-key projection rule is built from.
• Market Data Identifier — the existing market_series key oresmd supersedes.
• Market Data Requirement — the logical side of the logical/physical distinction oresmd sits on the physical side of.
• Dual-curve discount+projection model — the still-BACKLOG task whose data model should agree with this URI's role query key on one representation.
• Migrate to oresmd, delete market_series qualifier and ore_key — the follow-on implementation capture tracking the per-field migration and deletion plan.