{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://optionincometools.com/research/schemas/early-assignment.json",
  "title": "Early-assignment prediction — observation",
  "description": "One observation = one short option position carried through (or past) an ex-dividend date. Records the model's prediction of early assignment and whether early assignment actually occurred, used to calibrate the early-assignment incentive heuristic. See https://optionincometools.com/research/early-assignment-prediction/ for the methodology.",
  "type": "object",
  "required": [
    "observationId",
    "screenTimestamp",
    "underlying",
    "optionType",
    "strike",
    "expiration",
    "exDividendDate",
    "dividendAmount",
    "remainingExtrinsicValue",
    "moneyness",
    "daysToExDividend",
    "interestRateAssumption",
    "modelPrediction",
    "methodologyVersion"
  ],
  "properties": {
    "observationId": { "type": "string" },
    "screenTimestamp": { "type": "string", "format": "date-time" },
    "underlying": { "type": "string" },
    "optionType": { "type": "string", "enum": ["call", "put"] },
    "strike": { "type": "number" },
    "expiration": { "type": "string", "format": "date" },
    "exDividendDate": { "type": "string", "format": "date" },
    "dividendAmount": { "type": "number", "minimum": 0 },
    "remainingExtrinsicValue": { "type": "number", "description": "Mark of the option minus its intrinsic value at the close before ex-div." },
    "moneyness": { "type": "number", "description": "(spot - strike) / strike for calls; (strike - spot) / strike for puts. Positive = ITM." },
    "daysToExDividend": { "type": "integer", "minimum": 0 },
    "interestRateAssumption": { "type": "number", "description": "Risk-free rate used in early-exercise threshold model." },
    "modelPrediction": {
      "type": "object",
      "required": ["earlyAssignmentExpected", "incentiveDollars"],
      "properties": {
        "earlyAssignmentExpected": { "type": "boolean" },
        "incentiveDollars": { "type": "number", "description": "Computed dividend (or interest income) minus remaining extrinsic value." },
        "thresholdRule": { "type": "string", "default": "incentive > 0 and >= 0.5x dividend" }
      }
    },
    "actualOutcome": {
      "type": ["object", "null"],
      "properties": {
        "assigned": { "type": "boolean" },
        "assignmentTimestamp": { "type": ["string", "null"], "format": "date-time" },
        "wasFalsePositive": { "type": "boolean", "description": "Model predicted assignment; none occurred." },
        "wasFalseNegative": { "type": "boolean", "description": "Model predicted no assignment; assignment occurred anyway." }
      }
    },
    "underlyingPriceAtScreen": { "type": "number" },
    "methodologyVersion": { "type": "string" },
    "dataProvider": { "type": "string", "default": "polygon.io" },
    "notes": { "type": ["string", "null"] }
  },
  "additionalProperties": false
}