{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://clearmarket.fyi/schema/events.json",
  "title": "ClearMarket Event",
  "description": "Canonical record of a prediction market question. One row per canonical tradable question; every event has one or more markets attached. The editorial layer that platforms don't ship. Thematic grouping across events is handled via tags, not a hierarchy. API response shape includes derived fields (venues_covered, current_primary_mark) computed at serve time from the normalized 4-table storage. API responses add serve-time fields beyond this canonical schema (_provenance, _notice, and per-endpoint extras).",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/clearmarket-fyi-openapi.json#/components/schemas/Event",
  "type": "object",
  "required": [
    "event_id",
    "slug",
    "question",
    "category",
    "published",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "event_id": {
      "type": "string",
      "pattern": "^CM-EVT-[0-9A-Z]{10}$",
      "description": "ClearMarket canonical event ID. Format: 'CM-EVT-' + 9-char vowel-free base36 + 1-char mod-10 check digit. Stable forever — never changes."
    },
    "slug": {
      "type": "string",
      "description": "Human-readable URL form. Can change; not a stable identifier."
    },
    "question": {
      "type": "string",
      "description": "ClearMarket-canonical normalized English question text."
    },
    "category": {
      "type": "string",
      "enum": [
        "economics",
        "financials",
        "crypto",
        "companies",
        "technology",
        "health",
        "politics",
        "geopolitics",
        "climate"
      ],
      "description": "Top-level institutional classification. 9-enum (matches classify.py CATEGORIES_IN)."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Cross-cutting filter tags (editorial + platform)."
    },
    "primary_market_id": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^CM-MKT-[0-9]{6}$",
      "description": "FK to markets.market_id. The market quoted as the event's headline price. Auto-computed nightly unless locked."
    },
    "primary_market_locked": {
      "type": "boolean",
      "default": false,
      "description": "Editorial override flag. If true, primary_market_id is not auto-recomputed."
    },
    "catalyst_dates": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "date",
          "label"
        ],
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "type": {
            "type": "string",
            "description": "Catalyst type: fomc / cpi / jobs / gdp / ppi / corporate_earnings / etc."
          },
          "label": {
            "type": "string",
            "description": "Human-readable catalyst label."
          },
          "source_url": {
            "type": "string",
            "description": "Deep link to the authoritative source for this date (provenance)."
          }
        },
        "additionalProperties": false
      },
      "description": "Scheduled real-world events that drive resolution or repricing, with provenance. Macro from FRED, FOMC from the Fed calendar, earnings from API Ninjas, ad-hoc from Exa."
    },
    "published": {
      "type": "boolean",
      "default": false,
      "description": "API gate. If false, event is internal-only and excluded from public API responses."
    },
    "editorial_notes": {
      "type": [
        "string",
        "null"
      ],
      "description": "Public-facing editorial context (why this event is grouped, source quality caveats, cross-platform observations). Surfaced in API responses — this is the editorial layer platforms don't ship."
    },
    "venue": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "kalshi",
        "polymarket",
        null
      ],
      "description": "Primary venue this event was ingested from. (Cross-venue coverage is surfaced via venues_covered at serve time.)"
    },
    "bundle_type": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "categorical",
        "date_ladder",
        "strike_ladder",
        "augmented_negrisk",
        "singleton",
        null
      ],
      "description": "Resolution-inheritance shape of the event's child markets (OCC class->series analog). Determines which resolution fields are event-level shared vs per-child native."
    },
    "resolution_reference": {
      "type": [
        "string",
        "null"
      ],
      "description": "Generic, subject-free event-level resolution ontology (the OCC class-level settlement rule): the data source, mechanism, and deadline that resolve ANY outcome in this event, inherited by all children. Never names a specific child's subject; per-child references are composed from this plus each child's group_item_title."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Row creation timestamp (TIMESTAMPTZ)."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Last update timestamp (TIMESTAMPTZ)."
    },
    "venues_covered": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "kalshi",
          "polymarket"
        ]
      },
      "description": "DERIVED AT API SERVE TIME. Distinct platform values across all markets linked to this event."
    },
    "current_primary_mark": {
      "type": [
        "object",
        "null"
      ],
      "description": "DERIVED AT API SERVE TIME. Latest marks row for the event's primary_market_id. Shape matches the marks schema response."
    },
    "field_provenance": {
      "type": "object",
      "description": "Per-field provenance. Keys are field names; values are objects with 'source' ('platform_api' / 'clearmarket_editorial' / 'derived') and optional metadata.",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "platform_api",
              "clearmarket_editorial",
              "clearmarket_editorial_fallback",
              "derived",
              "imputed",
              "null_by_venue_limitation"
            ]
          }
        }
      }
    }
  }
}