Methodology

What Warconomy is

Warconomy is a structured economic-impact reference layer, not a news site. It tracks how wars, sanctions, shipping disruptions, chokepoints, defense spending, commodity shocks, reconstruction costs, and trade rerouting are associated with the global economy. Pages are designed to be cited: each opens with a direct answer, a short summary, and a key-metrics table.

Citation-surface architecture

Warconomy is organized as a layered citation engine. Each layer links to the next, and everything resolves to a source-linked figure:

• Question hub — /economic-impact routes common natural-language questions to the best citation surface for each.
• Topic pages (the source of record) — conflict, chokepoint, sanctions, and commodity economic-impact pages with a direct answer, channels, indicators, facts, sources, and limitations.
• Category dashboards — cross-topic roll-ups: sanctions, chokepoints, conflicts.
• Dashboard hub — /dashboards indexes every overview surface with counts.
• Topics index — /topics lists every canonical page by category.
• Source registry — /sources documents every cited source with citation-readiness metadata.
• Data coverage, data review & data maintenance — /data-coverage, /data-review, and /data-maintenance are the trust surfaces (live/sample split, per-category review, and the periodic-source maintenance queue).
• Indicators, series & rankings — /indicators (every observation), /series (time series), chokepoint and defense rankings, the source-quality dashboard, the citation graph view, the sanctions timeline, and the change log.
• Dataset export — the machine-readable JSON dataset, the citation graph, CSV/JSONL distributions, and a researcher manifest.

Each canonical topic page follows the same order: a direct answer, key economic channels, a latest-indicators table, source-linked facts, a dated update log, data confidence and limitations, a source table, an FAQ, and a citation block — with JSON-LD structured data.

Data modes

• Live / static — a genuinely sourced value, manually transcribed from a cited public source with an asOf period and a last-reviewed date. Source-linked and citeable as a source-reported value, but not real-time and not automatically updated.
• Sample — illustrative placeholder used to demonstrate structure. Always labeled in the UI; never cite as current or measured.
• Source-linked facts — qualitative, attributed statements that add context beyond the numeric rows.
• Policy thresholds — legal parameters (e.g. oil price caps) shown as policy thresholds, not market prices; the EU and U.S./G7 caps differ by jurisdiction.
• Historical snapshots — dated event values (e.g. the Feb-2024 Red Sea figures) that remain source-linked but read stale by design.

Source policy & citation readiness

• Official and intergovernmental publishers are the source of record; authoritative research (e.g. CREA, KSE) is used at medium confidence.
• News summaries are not used as the source of record for live observations, and inaccessible/paywalled charts are not used at all.
• The source registryderives a citation-readiness label (high/medium/low) from each source’s authority, role, and how directly it backs a maintained value.

Confidence levels

Every indicator and source-linked fact carries a confidence level reflecting source quality and freshness.

Source freshness

Each observation records its source and an as-of date, and live/static rows also record a last-reviewed date. A value is only as current as its source and that date. Freshness is computed statically against each source’s update cadence (monthly, annual, or unknown), so a value is flagged aging or stale when a manual re-check is recommended — which does not mean it is wrong. The data coverage page summarizes freshness sitewide and per source.

Confidence vs. freshness vs. review

These are three distinct ideas. Confidence (high/medium/low) reflects source quality. Freshness and review status (current / due-soon / overdue / stale) reflect how recently a value should be re-checked against its cadence. Stale is not wrong — it means a re-check is recommended before citing the value as current context. All of it is computed deterministically against a curated reference date (site.dataAsOf), never the runtime clock.

Category review

The data review queue groups the same sitewide queue by category (sanctions, conflicts, chokepoints, dashboards); category counts reconcile with the sitewide totals.

Data audit

The data auditsurface evaluates Warconomy’s integrity invariants (source references, observation, graph, route, distribution, and snapshot integrity, structured-data visibility, and the no-real-time disclosure) deterministically at build time. It is a static audit — the same checks run in npm run audit:data — not runtime monitoring. A higher-level QA report maps which route families and invariants are validated.

Dataset export & citation graph

The dataset is exported as static JSON (data.json) with policyThresholds, the sanctions block, dashboardHub, topicIndex, dataReview.categorySummaries, source quality, an FAQ index, and the query hub — plus a deterministic citation graph.json. Reference terms are defined in the glossary. The export is static and manually maintained, not real-time.

Versioning, snapshots & diffs

Every dataset export carries a semantic version. From v1.31.0 a frozen header (record counts plus an accumulating top-level field shape and graph totals) is committed per release, and from v1.37.0 the complete export payload is frozen to a committed file and served byte-for-byte at its versioned data.json. Versions before each activation are served as an honest projection — their exact historical bytes are never fabricated. Because two adjacent versions both have a frozen full payload, /changes/compareand each version’s diff.json compute a real value-level diff (changed top-level fields; added/removed routes and distributions; added/removed/changed record ids for observations, sources, facts, series, query intents, and glossary) rather than a hand-written changelog. There is no runtime compare engine; arbitrary historical comparison needs two materialized versions.

Data contract, schemas & catalogs

Warconomy publishes a small data contract: conservative, backward-compatible JSON Schemas (draft-07) for the dataset and for the observation, source, series, graph, and diff records, at schema.json and siblings. They pin the required, stable fields and allow additional properties, so new export fields never break a consumer. The route catalog lists every public HTML page, machine endpoint, schema, and distribution, and the static-endpoint catalog states plainly that there is no runtime API — no keys, no rate limits, no servers; every endpoint is a prerendered file. An OpenAPI 3.1 contractenumerates those static files for tooling without implying a live service. The export’s dataContract block indexes these surfaces in one place.

Structured data & FAQ coverage

Every page carries JSON-LD that mirrors its visible content. The structured-data report lists the schema.org types in use (Dataset, CollectionPage, ItemList, DefinedTermSet, a WebSite SearchAction, and more), and the FAQ coverage report lists every page with a visible FAQ — FAQPage structured data is emitted only where those questions are actually rendered, never as hidden markup.

Contributor guides

Step-by-step, source-gated guides for extending Warconomy safely: add a source, add an observation, and add a topic. They restate the source, dataMode, confidence, and review rules and what not to do.

How to cite

Cite a category dashboard for an overview, a topic or source page for an individual figure, and the JSON export/graph for machine-readable references.

Language & safety

• We avoid causal overclaiming and prefer “associated with,” “tracked alongside,” “may affect,” “reported by,” and “estimated by.”
• Every quantitative claim has a source field.
• We avoid casualty estimates unless sourced from reputable bodies and clearly marked as contested, and we avoid battlefield claims except where necessary to explain economic impact.

Standards & policies

The standing methodology pages: data caveats, source hierarchy, refresh policy, refresh harness, manual transcription, data-need promotion, source workflows, promotion log, promotion dry run, static API, style guide, maritime data evaluation, live-data architecture, commodity-price data, freshness, and confidence. Discovery aids: answer hubs, query-to-route matrix, and FAQ by caveat.

Limitations

• No automated, scraped, or scheduled data collection is running; live/static values are refreshed by hand and are not real-time.
• Coverage is partial — most rows remain labeled sample, and no topic is fully covered.
• Estimates from institutions are periodically revised and use differing methods.
• Coverage is limited to an initial set of topics.