{
  "$comment": "Schema for the AtomProphet Cascade Graph data model. Describes the shape of nodes and edges. Values in the companion sample file (cascade-sample-copper.json) are real; this file documents the fields.",
  "generated": "2026-06-23",
  "top_level": {
    "meta": "Object. Graph-level metadata (counts, generation date, lens families).",
    "nodes": "Array of node objects (see node schema).",
    "edges": "Array of directed edge objects (see edge schema).",
    "loops": "Array of curated closed feedback loops (reinforcing/balancing)."
  },
  "node": {
    "id": "string. Stable unique id. Terminal (ticker) nodes use 'TICKER_SYM (Company)'.",
    "label": "string. Human-readable display label.",
    "type": "enum: driver | chokepoint | geography | jurisdiction | substitute | terminal.",
    "lenses": "array<string>. Thematic lens keys this node belongs to.",
    "why_it_matters": "string. Plain-language reason this node is in the system.",
    "honest_read": "string. Candid caveat: counter-forces, drawdowns, data gaps.",
    "geography": "array<string>. Relevant countries/regions (where applicable).",
    "metrics": "array<metric>. Sourced quantitative reference points (see metric).",
    "terminals": "array<terminal>. (chokepoints) Candidate tickers + vetted instruments.",
    "further_reading": "array<reading>. Vetted external sources (title/publisher/url/year)."
  },
  "metric": {
    "label": "string. What the figure measures.",
    "value": "string. The figure, with units, as published.",
    "source": "string. Issuing institution.",
    "url": "string. Link to the primary source."
  },
  "terminal": {
    "ticker": "string. Legacy single symbol (kept for back-compat).",
    "note": "string. Short company/ETF descriptor.",
    "honest_read": "string. Candid per-ticker read (returns + drawdown).",
    "vetted": "array<vetted_instrument>. The 2-3 screened expressions (see below)."
  },
  "vetted_instrument": {
    "ticker": "string. Symbol as traded.",
    "venue": "string. Listing venue (e.g. NYSE, NYSE Arca, Borsa Italiana, OTC).",
    "flag": "enum: clean | foreign | otc_adr | etf | no_play. Honesty flag.",
    "tier": "enum: Deep | Liquid | Moderate | Thin | VeryThin | Unknown. Liquidity tier.",
    "dollar_volume_h": "string. Median daily $-volume (human-readable, e.g. '$879.0M').",
    "exposure_note": "string. Sourced description of the thematic exposure.",
    "live_verified": "boolean. True if liquidity was verified against the live market feed."
  },
  "edge": {
    "source": "string. id of the upstream node.",
    "target": "string. id of the downstream node.",
    "rel": "string. Machine relation key (e.g. drives_demand_for, is_bottleneck_for).",
    "label": "string. Plain-language relation ('drives demand for').",
    "polarity": "int. +1 amplifying / -1 dampening.",
    "basis": "enum: measured | established | reasoned. Evidence grade of the link.",
    "confidence": "enum: strong | moderate | emerging.",
    "lag_months": "int. Approximate mechanism lag in months.",
    "claim": "string. The asserted mechanism in one sentence.",
    "source_pub": "string|null. Issuing institution if measured.",
    "source_url": "string|null. Primary source link if measured.",
    "magnitude": "string|null. Qualitative magnitude.",
    "timeframe": "string|null. Qualitative horizon."
  },
  "loop": {
    "nodes": "array<string>. Ordered node ids forming the closed cycle.",
    "kind": "enum: reinforcing | balancing.",
    "note": "string. What the loop does."
  }
}