timeprice 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a91644504f73e6324d522d189233539a5515ca51cf0be58b1a34da90ff78220d
-  data.tar.gz: f6120dc38bb433e1dc8ac56e523b3c547d9323b578f34a27bddee3e43b48c9a2
+  metadata.gz: 6f5a76db32571e7ab2f09f9e22e1d90d420b5bdcf474baff6b523f2c8998c72b
+  data.tar.gz: 96e212aaa5aac2cfe4defc28364498ef49241de34161cb3e301f4886a19650d0
 SHA512:
-  metadata.gz: b8b0f99a9962bad944a02499761a586e860d50a3707e70de4d1549c6bf624ea5bf1a9d1d2beae488abdfc6646d825320259a196bfac177e64c25edab90e721e5
-  data.tar.gz: 54bb2545e7c9f9bbdb202994f3d5f53bb020a36bde0a2d8627c734a1c0e4312fcbe0237ce2b23409af9253ddc809ae74129dec43b17b94c559bcefa8917142cf
+  metadata.gz: 4148766e8c3dee2243ed933868d23cb2d79959db1581d07de654e1bab87325de98eacb2cd41200e1f765f3d94dde03472dc5d02a37e2e2f059fc8a651ac40666
+  data.tar.gz: a51e3132f616bc0e468b0f9afdff9ab71a2017abd25eed5ffd45cecc4c385d58f4670ffeeb5cc8bc5f4143f639a42d92f88a2d6e4f81957171d6c3207982d5ee

data/CHANGELOG.md

@@ -5,6 +5,28 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-05-11
+
+### Changed
+- **Schema v2 → v3.** Breaking change to the bundled data contract. v0.4.x
+  data files will not load on v0.5.0.
+  - New top-level `data/manifest.json` — single source of truth for which
+    countries and currencies the bundle supports. `Supported.countries` /
+    `Supported.currencies` derive from it at runtime; the hardcoded Ruby
+    constants `Supported::COUNTRIES` / `CURRENCIES` are gone. Custom callers
+    that referenced those constants must switch to the method form.
+  - CPI files use nested `series: { monthly, annual }` and a structured
+    `index: { base_period, rebased_at }` block in place of the freeform
+    `base_year` string. Top-level `source` and `updated_at` removed —
+    `providers[]` is the source of truth for provenance.
+  - FX year files now carry `provenance` + `providers` blocks, symmetric
+    with CPI.
+  - All annual FX (today only VND from World Bank) lives in
+    `data/fx/usd/_annual.json` — the single canonical source, every year.
+    Per-year files (`data/fx/usd/<year>.json`) hold daily rates only. Pre-1999
+    stub year files are gone. `Exchange.lookup_usd_base` collapses to a
+    two-tier chain (daily → annual fallback), one source per tier.
+
 ## [0.4.0] - 2026-05-11
 
 ### Changed

data/README.md

@@ -101,8 +101,9 @@ Coverage is derived from the bundled `data/` files. Re-check with `timeprice sou
 | Vietnam | VND | IMF Data Portal CPI dataflow (monthly primary) + World Bank `FP.CPI.TOTL` (annual fallback) | Monthly + annual | 1995 → present |
 
 **FX (USD base):** ECB reference rates via Frankfurter for **EUR / GBP / JPY**, daily
-1999 → present. **VND** uses the World Bank annual average (`PA.NUS.FCRF`) broadcast to
-every day in the year, from 1983 → present.
+1999 → present. **VND** uses the World Bank annual average (`PA.NUS.FCRF`), one value
+per year, from 1983 → present. VND results are tagged `granularity: :annual` so callers
+know they got the annual fallback rather than a daily rate.
 
 Triangulated cross-rates (e.g. GBP → JPY) go through USD on the same effective date.
 Weekend/holiday dates fall back up to 7 days to the nearest prior trading day.
@@ -265,6 +266,21 @@ license — see `DATA_LICENSES.md` and `NOTICE` for the full table and license U
 If you redistribute results derived from this gem, reproduce the relevant attribution
 strings. `timeprice sources` prints them in plain text and as JSON.
 
+## Data format
+
+Bundled data lives under `data/` in schema v3 and is self-describing:
+
+- `data/manifest.json` — the supported set (countries, currencies, FX years).
+- `data/cpi/<country>.json` — CPI for one country: `series.{monthly,annual}`,
+  structured `index` block, `provenance` ranges, `providers` attribution.
+- `data/fx/usd/<year>.json` — daily USD-base FX rates for one year (one file
+  per year, EUR/GBP/JPY).
+- `data/fx/usd/_annual.json` — annual USD-base FX rates across all years for
+  currencies sourced at annual resolution (today only VND). Used as the
+  fallback tier when no daily rate covers the requested date.
+
+`scripts/check_schema_stability.rb` enforces the shape in CI.
+
 ## Author
 
 Built by [Patrick](https://github.com/patrick204nqh).