Story: Make the oresmd URI grammar explicit and typed

Table of Contents

This page documents a story in Sprint 26. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

1. Goal

Every oresmd URI states what it means without the reader knowing a default or a family's coordinate convention: each coordinate dimension is a named query key, every key the grammar defines is present, and every key is declared identity or coordinate so the series identity is a declaration rather than a special case.

2. Status

Field Value
State DONE
Parent sprint Sprint 26
Now Nothing.
Waiting on Nothing.
Next Nothing.
Last touched 2026-10-04

3. Acceptance

  • No key's absence carries meaning: a key the grammar defines for a (type, quote) pair is always present, with defaults materialised by the parser and emitted by the writer.
  • No coordinate is a comma-joined bag: each dimension is a named, typed query key, and ATM is a delta rather than a strike.
  • Every query key is declared identity or coordinate in its quote-type model, and the series identity is the declared identity keys and nothing else.
  • One canonical coordinate form exists in the URI and in the database; the registry's point_id is derived, not stored.
  • The full corpus import passes and runs in the default test set, so a regression is visible without a hidden tag.
  • The design record market_data_urn.org describes the grammar that ships.
  • todaysmarket.xml is owned by ores.refdata and the placement rule is recorded beside the other ORE configuration documents.

4. Tasks

Task State Start End Description
Scaffold story: Make the oresmd URI grammar explicit and typed DONE 2026-10-01 2026-10-01 Story scaffolding rides this task: documents, sprint wiring, and the scaffold PR. Close it before merging that PR.
Declare the oresmd coordinates in the models DONE 2026-10-01 2026-10-01 Add the Coordinates table and the identity/coordinate role to the twelve quote-type models, and remove point. No generated code changes.
Generate the oresmd grammar from the models DONE 2026-10-01 2026-10-01 Generate the identifier structs, the parser, the writer and the key projections from the declared coordinates, and rewrite the design record for the new URI spelling.
Move the stored oresmd identity and coordinate DONE 2026-10-01 2026-10-01 Unify the stored coordinate on one canonical, self-describing form, derive the registry's point_id rather than storing it, and migrate existing rows from the producer's own key.
Close out the grammar change DONE 2026-10-01 2026-10-01 Promote the corpus walk out of the hidden tag, correct the record, and settle the todaysmarket.xml ownership question beside the other ORE configuration documents.

5. Decisions

  • The coordinate is typed, not a bag. point is removed. Each dimension is a named query key: maturity, expiry, tenor, strike, delta, call_put, premium, cap_floor, shift, strip, seniority, restructuring, from, to, date, second, period, dst, factor, second_factor, month. A reader needs no family convention.
  • No key's absence carries meaning. Where the grammar defines a default, the parser materialises it and the writer emits it. model is always present for type=vol, and no reader has to know that an absent model once meant lognormal.
  • ATM is a delta, not a strike. The parser put the third surface token in strike; it belongs in delta, which is what ORE's own curveconfig.xml calls a dimension.
  • Identity and coordinate are declared per key. Each quote-type model gives every query key a role. The series identity is the declared identity keys, so the model subtype leaves the coordinate set and two vol models become two series.
  • Four volatility families gain a quote type. swaption for IR, and an option member for FX, equity and commodity. Without them the grammar would keep a silent default where it has just removed the others.
  • One canonical coordinate. The URI and the database use one self-describing form; the registry's ORE-form point_id is derived for key projection.
  • Today's market is configuration, and ores.refdata owns it. The rule: where ORE names a document in the Analytics block it belongs to ores.analytics; where a run or an analytic merely references it, it belongs to the component that owns the concept. curveconfig.xml and todaysmarket.xml name curves and sets of curves, so both are ores.refdata. The <Simulation><Market> documents configure an analytic's market and are ores.analytics. ore_market.xml is a run document and is ores.reporting.

The full analysis is in The oresmd URI grammar: silent defaults and the untyped coordinate.

6. Out of scope

  • Modelling curveconfig.xml or todaysmarket.xml as entities. This story settles who owns today's market, not what its entities are.

7. Result

Every unit landed. The generated grammar it built was later replaced by the hand-written codecs of Rewrite the oresmd grammar as a hand-written codec checked against ORE.

Emacs 29.3 (Org mode 9.6.15)