{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/metricduck-com/json-schema/metricduck-com-earnings-insight-schema.json",
  "title": "EarningsInsight",
  "description": "Complete earnings insights from LLM-extracted 8-K release.\n\nThis model represents the full structured output from the earnings processor,\nincluding financial metrics, margins, segments, guidance, and commentary.",
  "x-generated": "2026-11-18",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/metricduck-com-openapi.json#/components/schemas/EarningsInsight",
  "properties": {
    "cik": {
      "type": "string",
      "title": "Cik"
    },
    "company_name": {
      "type": "string",
      "title": "Company Name"
    },
    "ticker": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Ticker"
    },
    "accession_number": {
      "type": "string",
      "title": "Accession Number"
    },
    "filing_date": {
      "type": "string",
      "format": "date",
      "title": "Filing Date"
    },
    "fiscal_period": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Fiscal Period"
    },
    "fiscal_year": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Fiscal Year"
    },
    "executive_summary": {
      "type": "string",
      "title": "Executive Summary"
    },
    "positive_highlights": {
      "items": {
        "$ref": "#/$defs/HighlightItem"
      },
      "type": "array",
      "title": "Positive Highlights"
    },
    "concerns": {
      "items": {
        "$ref": "#/$defs/HighlightItem"
      },
      "type": "array",
      "title": "Concerns"
    },
    "key_highlights": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Key Highlights"
    },
    "management_commentary": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Management Commentary"
    },
    "revenue": {
      "anyOf": [
        {
          "$ref": "#/$defs/EarningsMetric"
        },
        {
          "type": "null"
        }
      ]
    },
    "net_income": {
      "anyOf": [
        {
          "$ref": "#/$defs/EarningsMetric"
        },
        {
          "type": "null"
        }
      ]
    },
    "operating_income": {
      "anyOf": [
        {
          "$ref": "#/$defs/EarningsMetric"
        },
        {
          "type": "null"
        }
      ]
    },
    "eps_diluted": {
      "anyOf": [
        {
          "$ref": "#/$defs/EarningsMetric"
        },
        {
          "type": "null"
        }
      ]
    },
    "eps_basic": {
      "anyOf": [
        {
          "$ref": "#/$defs/EarningsMetric"
        },
        {
          "type": "null"
        }
      ]
    },
    "withheld": {
      "items": {
        "$ref": "#/$defs/WithheldField"
      },
      "type": "array",
      "title": "Withheld",
      "description": "Metrics withheld by the serve-cap or the currency gate (served null + a 'check the filing' note); empty when nothing was withheld."
    },
    "advisories": {
      "items": {
        "$ref": "#/$defs/FieldAdvisory"
      },
      "type": "array",
      "title": "Advisories",
      "description": "Groups of figures that cannot all be right, served in full with the disagreement named; empty when nothing was flagged."
    },
    "beat_miss": {
      "anyOf": [
        {
          "$ref": "#/$defs/BeatMissAssessment"
        },
        {
          "type": "null"
        }
      ]
    },
    "cash_flow": {
      "anyOf": [
        {
          "$ref": "#/$defs/CashFlowInsight"
        },
        {
          "type": "null"
        }
      ],
      "description": "Cash flow metrics with accrual quality (v5+)"
    },
    "guidance_revisions": {
      "items": {
        "$ref": "#/$defs/GuidanceRevision"
      },
      "type": "array",
      "title": "Guidance Revisions",
      "description": "Guidance revisions (raised/lowered)"
    },
    "management_assessment": {
      "anyOf": [
        {
          "$ref": "#/$defs/ManagementAssessment"
        },
        {
          "type": "null"
        }
      ],
      "description": "Management tone and disclosure quality (v5+)"
    },
    "material_events": {
      "items": {
        "$ref": "#/$defs/MaterialEvent"
      },
      "type": "array",
      "title": "Material Events",
      "description": "Material events (M&A, regulatory)"
    },
    "gross_margin": {
      "anyOf": [
        {
          "$ref": "#/$defs/MarginMetric"
        },
        {
          "type": "null"
        }
      ]
    },
    "operating_margin": {
      "anyOf": [
        {
          "$ref": "#/$defs/MarginMetric"
        },
        {
          "type": "null"
        }
      ]
    },
    "net_margin": {
      "anyOf": [
        {
          "$ref": "#/$defs/MarginMetric"
        },
        {
          "type": "null"
        }
      ]
    },
    "special_items": {
      "items": {
        "$ref": "#/$defs/SpecialItem"
      },
      "type": "array",
      "title": "Special Items"
    },
    "guidance": {
      "items": {
        "$ref": "#/$defs/src__models__earnings_insights__GuidanceItem"
      },
      "type": "array",
      "title": "Guidance"
    },
    "segments": {
      "items": {
        "$ref": "#/$defs/SegmentData"
      },
      "type": "array",
      "title": "Segments"
    },
    "operational_metrics": {
      "additionalProperties": {
        "$ref": "#/$defs/OperationalMetric"
      },
      "type": "object",
      "title": "Operational Metrics"
    },
    "filing_metadata": {
      "anyOf": [
        {
          "$ref": "#/$defs/FilingMetadata"
        },
        {
          "type": "null"
        }
      ]
    },
    "form_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Form Type"
    },
    "source_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Source Url"
    },
    "items": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Items"
    },
    "acceptance_datetime": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Acceptance Datetime"
    },
    "extraction_confidence": {
      "type": "number",
      "maximum": 1.0,
      "minimum": 0.0,
      "title": "Extraction Confidence",
      "description": "Confidence score 0.0-1.0"
    },
    "llm_model": {
      "type": "string",
      "title": "Llm Model"
    },
    "processing_cost_usd": {
      "type": "number",
      "title": "Processing Cost Usd"
    },
    "processed_at": {
      "type": "string",
      "format": "date-time",
      "title": "Processed At"
    }
  },
  "type": "object",
  "required": [
    "cik",
    "company_name",
    "accession_number",
    "filing_date",
    "executive_summary",
    "extraction_confidence",
    "llm_model",
    "processing_cost_usd",
    "processed_at"
  ],
  "$defs": {
    "BeatMissAssessment": {
      "properties": {
        "revenue_characterization": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Revenue Characterization"
        },
        "eps_characterization": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Eps Characterization"
        }
      },
      "type": "object",
      "title": "BeatMissAssessment",
      "description": "Beat/miss assessment vs analyst expectations (v3.4+)"
    },
    "CashFlowInsight": {
      "properties": {
        "operating_cash_flow": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Operating Cash Flow",
          "description": "Operating cash flow (current period)"
        },
        "ocf_prior_year": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Ocf Prior Year",
          "description": "Operating cash flow (prior year period)"
        },
        "ocf_growth_pct": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Ocf Growth Pct",
          "description": "OCF year-over-year growth percentage"
        },
        "free_cash_flow": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Free Cash Flow",
          "description": "Free cash flow (current period)"
        },
        "fcf_prior_year": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Fcf Prior Year",
          "description": "Free cash flow (prior year period)"
        },
        "fcf_growth_pct": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Fcf Growth Pct",
          "description": "FCF year-over-year growth percentage"
        },
        "capex": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Capex",
          "description": "Capital expenditures"
        },
        "capex_prior_year": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Capex Prior Year",
          "description": "Capital expenditures (prior year period)"
        },
        "capex_growth_pct": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Capex Growth Pct",
          "description": "CapEx year-over-year growth percentage"
        },
        "capex_quarterly_series": {
          "anyOf": [
            {
              "items": {
                "type": "number"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Capex Quarterly Series",
          "description": "Recent quarterly CapEx series (oldest-to-newest, absolute positive values, excluding TTM). Sourced from the FCF reconciliation table when present."
        },
        "ocf_to_net_income_ratio": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Ocf To Net Income Ratio",
          "description": "OCF / Net Income ratio (cash conversion)"
        },
        "fcf_to_net_income_ratio": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Fcf To Net Income Ratio",
          "description": "FCF / Net Income ratio"
        },
        "accrual_quality": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Accrual Quality",
          "description": "Accrual quality assessment: high, moderate, low, concern"
        },
        "accrual_quality_note": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Accrual Quality Note",
          "description": "Explanation of accrual quality assessment"
        },
        "period": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Period",
          "description": "Reporting basis of the monetary cash-flow fields: 'q_current' (the quarter alone), 'fy_current' (fiscal year to date / full year), or 'not_assessed'. Absent on rows produced before #1358."
        },
        "scale": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Scale",
          "description": "Unit scale of the monetary fields. The service normalizes all cash-flow values to raw dollars, so this is 'absolute'. Consumers MUST NOT re-scale when scale=='absolute' (a missing/absent scale on older API responses means the values are in millions).",
          "default": "absolute"
        },
        "provenance": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/Receipt"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Provenance",
          "description": "Source receipt(s) for the as-released cash-flow block: verbatim quote + deep-link into the 8-K cash-flow statement. `covers` names the printed figures attested (operating_cash_flow, capex); free_cash_flow is derived."
        }
      },
      "type": "object",
      "title": "CashFlowInsight",
      "description": "Cash flow metrics from earnings release (v5+)."
    },
    "EarningsMetric": {
      "properties": {
        "q_current": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Q Current"
        },
        "q_prior_year": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Q Prior Year"
        },
        "annual_current": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Annual Current"
        },
        "annual_prior_year": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Annual Prior Year"
        },
        "yoy_growth": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Yoy Growth"
        },
        "currency": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Currency",
          "description": "ISO currency of every figure on this metric, when the release's own table names it (r111). Set only for a non-USD reporter's figure read from a table printed in the company's reporting currency; None otherwise (a USD reporter's figures are dollars)."
        },
        "provenance": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/Receipt"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Provenance",
          "description": "Per-figure receipts, each attesting only the period(s) in its own `covers` list (see Receipt) — a receipt is never emitted for a field it doesn't explicitly cover, even when other fields on this same metric are attested. Null when the value is legacy-filled, v3-absent, or the source quote is unvalidated: absence of a receipt is not evidence the value is wrong, only that no attested quote is available for it (fail-closed)."
        }
      },
      "type": "object",
      "title": "EarningsMetric",
      "description": "Metric with quarterly and annual values"
    },
    "FieldAdvisory": {
      "properties": {
        "metrics": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Metrics",
          "description": "Every metric in the disagreement — none of them is withheld, and the advisory does not claim to know which one is wrong."
        },
        "reason": {
          "type": "string",
          "title": "Reason",
          "description": "Machine tag: 'margin_operand_mismatch' (a margin, its operand and revenue cannot all three be right)."
        },
        "note": {
          "type": "string",
          "title": "Note",
          "description": "Human-facing explanation ('… check the filing')."
        },
        "filing_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Filing Url",
          "description": "Link to the source filing to check the reported figures."
        }
      },
      "type": "object",
      "required": [
        "metrics",
        "reason",
        "note"
      ],
      "title": "FieldAdvisory",
      "description": "Figures that are mutually inconsistent, served anyway with the disagreement named.\n\n⛔ The opposite of `WithheldField`: nothing is nulled. It exists because the\ndetector can prove a row is wrong without being able to say WHICH member is wrong.\n`margin/100 x revenue == operand` has three terms, and measured against audited\nXBRL the broken one is revenue about as often as it is the operand — AMTB serves\nrevenue $18,030 against a filed $100,737,000 while its own net income and margin\nare both right, and Visa serves an operating income of -$44.00M against a filed\n$6.877B while its revenue is right. Same three-number signature, opposite culprits.\n\nSo this names every member of the disagreement and deletes none of them. The\nprevious design picked one and was wrong 7 times in 26 (#3218), and the one after\nthat logged silently, which left Visa serving a confirmed-wrong figure with no\nreader-visible signal at all.\n\nAdditive + default-empty, so an older worker simply ignores it."
    },
    "FilingMetadata": {
      "properties": {
        "form_type": {
          "type": "string",
          "title": "Form Type",
          "description": "SEC form type (typically '8-K' for earnings)",
          "default": "8-K"
        },
        "items": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Items",
          "description": "8-K item numbers (e.g., ['2.02', '9.01'])"
        },
        "source_url": {
          "type": "string",
          "title": "Source Url",
          "description": "SEC EDGAR URL for the filing",
          "default": ""
        },
        "acceptance_datetime": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ],
          "title": "Acceptance Datetime",
          "description": "SEC acceptance timestamp (UTC)"
        },
        "period_end": {
          "anyOf": [
            {
              "type": "string",
              "format": "date"
            },
            {
              "type": "null"
            }
          ],
          "title": "Period End",
          "description": "Quarter/period end date"
        }
      },
      "type": "object",
      "title": "FilingMetadata",
      "description": "Metadata from SEC 8-K filing.\n\nIncludes form type, items covered, SEC source URL, and timing information."
    },
    "GuidanceRevision": {
      "properties": {
        "metric": {
          "type": "string",
          "title": "Metric",
          "description": "Metric name (e.g., 'Revenue', 'EPS')"
        },
        "period": {
          "type": "string",
          "title": "Period",
          "description": "Guidance period (e.g., 'FY2026', 'Q2 2025')"
        },
        "revision_direction": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Revision Direction",
          "description": "Direction: raised, lowered, maintained, narrowed"
        },
        "current_low": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Current Low",
          "description": "Current guidance low"
        },
        "current_high": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Current High",
          "description": "Current guidance high"
        },
        "current_point": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Current Point",
          "description": "Current guidance point estimate"
        },
        "prior_low": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Prior Low",
          "description": "Prior guidance low"
        },
        "prior_high": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Prior High",
          "description": "Prior guidance high"
        },
        "prior_point": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Prior Point",
          "description": "Prior guidance point estimate"
        },
        "current_point_text": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Current Point Text",
          "description": "Qualitative/range current point when not a single number"
        },
        "prior_point_text": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Prior Point Text",
          "description": "Qualitative/range prior point when not a single number"
        },
        "revision_magnitude_pct": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Revision Magnitude Pct",
          "description": "Magnitude of revision as percentage"
        },
        "commentary": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Commentary",
          "description": "Management commentary on revision"
        }
      },
      "type": "object",
      "required": [
        "metric",
        "period"
      ],
      "title": "GuidanceRevision",
      "description": "Guidance revision tracking (raised/lowered/maintained)."
    },
    "HighlightItem": {
      "properties": {
        "text": {
          "type": "string",
          "title": "Text"
        },
        "signal": {
          "type": "string",
          "title": "Signal"
        }
      },
      "type": "object",
      "required": [
        "text",
        "signal"
      ],
      "title": "HighlightItem",
      "description": "Highlight with sentiment signal"
    },
    "ManagementAssessment": {
      "properties": {
        "overall_tone": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Overall Tone",
          "description": "Tone: confident, cautious, defensive, evasive"
        },
        "tone_confidence": {
          "anyOf": [
            {
              "type": "number",
              "maximum": 1.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Tone Confidence",
          "description": "Confidence in tone assessment (0.0-1.0)"
        },
        "disclosure_quality": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Disclosure Quality",
          "description": "Disclosure quality: transparent, adequate, opaque"
        },
        "strategy_clarity": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Strategy Clarity",
          "description": "Strategy clarity: clear, adequate, unclear"
        },
        "specific_vs_vague": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Specific Vs Vague",
          "description": "Specificity: highly_specific, specific, vague, very_vague"
        },
        "key_strategic_themes": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Key Strategic Themes",
          "description": "Key strategic themes mentioned"
        },
        "positive_language_examples": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Positive Language Examples",
          "description": "Examples of positive language used"
        },
        "new_risks_mentioned": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "New Risks Mentioned",
          "description": "New risks mentioned in this release"
        }
      },
      "type": "object",
      "title": "ManagementAssessment",
      "description": "Management tone and disclosure quality analysis."
    },
    "MarginMetric": {
      "properties": {
        "current": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Current",
          "description": "Current period margin as percentage"
        },
        "prior_year": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Prior Year",
          "description": "Prior year period margin as percentage"
        },
        "change_bps": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Change Bps",
          "description": "Year-over-year change in basis points (100 bps = 1.0%)"
        }
      },
      "type": "object",
      "title": "MarginMetric",
      "description": "Margin metric in percentage terms with YoY change in basis points.\n\nExample:\n    Gross margin: 10.85% current, 10.42% prior year → +43 bps"
    },
    "MaterialEvent": {
      "properties": {
        "event_type": {
          "type": "string",
          "title": "Event Type",
          "description": "Event type: acquisition, divestiture, regulatory, restructuring, legal"
        },
        "description": {
          "type": "string",
          "title": "Description",
          "description": "Description of the event"
        },
        "counterparty": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Counterparty",
          "description": "Counterparty involved (e.g., acquired company)"
        },
        "value_millions": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Value Millions",
          "description": "Transaction value in millions USD"
        },
        "status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Status",
          "description": "Status: pending, closed, announced"
        },
        "signal": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Signal",
          "description": "Signal: positive, negative, attention"
        }
      },
      "type": "object",
      "required": [
        "event_type",
        "description"
      ],
      "title": "MaterialEvent",
      "description": "Material corporate event (M&A, regulatory, restructuring)."
    },
    "OperationalMetric": {
      "properties": {
        "current": {
          "title": "Current",
          "description": "Current period value (can be float, int, or string)"
        },
        "prior_year": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ],
          "title": "Prior Year",
          "description": "Prior year period value"
        },
        "growth_pct": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Growth Pct",
          "description": "Year-over-year growth percentage"
        },
        "unit": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Unit",
          "description": "Unit of measurement (e.g., 'members', 'locations', 'vehicles')"
        }
      },
      "type": "object",
      "required": [
        "current"
      ],
      "title": "OperationalMetric",
      "description": "Operational/non-financial metric (KPI).\n\nExamples: Active users, locations, memberships, vehicles sold, subscriptions"
    },
    "Receipt": {
      "properties": {
        "covers": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Covers",
          "description": "Period keys this receipt attests to, e.g. ['q_current']. A receipt never implies coverage of a period outside this list."
        },
        "quote": {
          "type": "string",
          "title": "Quote",
          "description": "Verbatim quote from the source filing the value was extracted from."
        },
        "viewer_url": {
          "type": "string",
          "title": "Viewer Url",
          "description": "Deep link into the source exhibit at the cited block. Pass-through from the producer's locator — never rebuilt downstream."
        },
        "block_id": {
          "type": "string",
          "title": "Block Id",
          "description": "Producer-assigned id of the source block the quote was extracted from. Version-scoped, NOT a durable identifier: it encodes the block's POSITION in one normalization of the exhibit, so re-extracting the same filing under a later producer version can move it — or leave it pointing at different content (#1890). Treat it as an internal coordinate, not a stable handle; `quote` + `viewer_url` are the pair that navigates back to the source."
        },
        "exhibit_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Exhibit Id",
          "description": "Id of the exhibit (within the filing) the block belongs to."
        }
      },
      "type": "object",
      "required": [
        "covers",
        "quote",
        "viewer_url",
        "block_id"
      ],
      "title": "Receipt",
      "description": "Per-figure provenance (\"receipt\") for one served financial metric (#1397).\n\nA receipt attests ONLY the period(s) listed in `covers` — e.g. a receipt\nwith `covers=[\"q_current\"]` says nothing about `q_prior_year` or the\nannual fields, which may come from a different source (see\n`EarningsMetric.provenance` for why a served metric can be mixed-source).\nNever infer coverage of a field this receipt doesn't explicitly list.\n\nLives in `base` (not `financial_statements`) so BOTH `financial_statements`\n(EarningsMetric/EarningsInsight) and `earnings_insights` (CashFlowInsight,\n#1813) can carry it without a circular import."
    },
    "SegmentData": {
      "properties": {
        "level": {
          "type": "integer",
          "maximum": 3.0,
          "minimum": 0.0,
          "title": "Level",
          "description": "Tree depth (0 = root, 1-3 = children)"
        },
        "name": {
          "type": "string",
          "title": "Name",
          "description": "Segment name"
        },
        "growth_yoy_pct": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Growth Yoy Pct",
          "description": "Year-over-year growth percentage"
        },
        "growth_yoy_pct_constant_currency": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Growth Yoy Pct Constant Currency",
          "description": "YoY growth in constant currency (if reported)"
        },
        "metric_type": {
          "type": "string",
          "title": "Metric Type",
          "description": "Type of metric ('revenue', 'users', 'gmv', etc.)",
          "default": "revenue"
        },
        "revenue": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Revenue",
          "description": "Current period revenue"
        },
        "prior_year_revenue": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Prior Year Revenue",
          "description": "Prior year period revenue"
        },
        "extraction_method": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Extraction Method",
          "description": "Extraction method: 'llm', 'regex', 'table_parser', 'migration'"
        },
        "children": {
          "items": {
            "$ref": "#/$defs/SegmentData"
          },
          "type": "array",
          "title": "Children",
          "description": "Child segments (next level down)"
        }
      },
      "type": "object",
      "required": [
        "level",
        "name"
      ],
      "title": "SegmentData",
      "description": "Hierarchical segment data with parent-child relationships.\n\nSegments can be geographic (U.S., International) or product-based (iPhone, Services).\nSupports up to 4 levels of hierarchy (L0 = root, L3 = most granular)."
    },
    "SpecialItem": {
      "properties": {
        "period": {
          "type": "string",
          "title": "Period",
          "description": "Fiscal period (e.g., 'Q2 FY2025')"
        },
        "description": {
          "type": "string",
          "title": "Description",
          "description": "Description of the special item"
        },
        "amount_millions": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Amount Millions",
          "description": "Amount in millions USD"
        },
        "per_share_impact": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Per Share Impact",
          "description": "Per-share impact (diluted)"
        },
        "note": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Note",
          "description": "Additional context or note"
        }
      },
      "type": "object",
      "required": [
        "period",
        "description"
      ],
      "title": "SpecialItem",
      "description": "Non-recurring or special item affecting earnings.\n\nExamples: Restructuring charges, asset impairments, tax benefits, litigation settlements"
    },
    "WithheldField": {
      "properties": {
        "metric": {
          "type": "string",
          "title": "Metric",
          "description": "Withheld metric: 'revenue' | 'net_income' | 'operating_income' | 'eps_diluted' | 'eps_basic' | 'gross_margin' | 'operating_margin' | 'net_margin' | 'cash_flow' (the whole cash-flow family) | 'segments' (segment monetary values; names are kept, and growth rates too except under 'segment_scale_mismatch', which keeps only those the release states) | 'guidance' (one or more forward-guidance figures; the qualitative text is retained)."
        },
        "reason": {
          "type": "string",
          "title": "Reason",
          "description": "Machine tag for why the field was withheld: 'serve_cap' (implausible magnitude, #1508), 'prior_scale' (the release's prior-year figure is a probable units error against the company's own filings, #3242), 'cash_flow_scale_revenue' (a cash-flow figure over $2B and at least 20x the release's own revenue; the whole cash-flow block is withheld) and the other 'cash_flow_scale_*' arms of the same check (the block withheld on other evidence of a units error; each reason's note says which), 'currency_unverified' (non-USD reporter whose per-figure currency is not yet recorded, #2615), 'margin_implausible' (a margin outside the range a margin can take), 'extractor_conflict' (a release whose results exist only as page images, or whose two readings put the quarters in opposite columns, where our two readings of the named figure disagree), 'image_transcription_unreconciled' (the same kind of release on a surface that shows one reading without the cross-check), 'net_income_sign_conflict' (a table-read net income whose sign contradicts the release's own net margin), 'table_reader_implausible' (a table-read quarterly figure that cannot be the release's: an income under $10K beside revenue of $10M or more, a negative revenue, or a revenue below net income and 20x below the company's filed revenue), 'segment_scale_mismatch' (segment amounts totalling 10^3 or 10^6 times the quarter's filed revenue), 'period_misread' (a figure read from another period's column of a 6-K release, listed against the filing) or 'figure_misread' (a listed figure that is not the company's own for the period: printed nowhere for that line, one segment's, or in cents) or 'figure_unchecked' (a 6-K figure printed only in a column that names no single period, r112).",
          "default": "serve_cap"
        },
        "note": {
          "type": "string",
          "title": "Note",
          "description": "Human-facing explanation ('… check the filing')."
        },
        "filing_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Filing Url",
          "description": "Link to the source filing to check the reported figure."
        }
      },
      "type": "object",
      "required": [
        "metric",
        "note"
      ],
      "title": "WithheldField",
      "description": "A metric that was withheld rather than served, and why. The reasons:\n\n- ``reason=\"serve_cap\"`` (#1508) — the figure exceeded the company's own SEC-filed\n  XBRL magnitude by more than the cap multiple (a probable scale error or\n  cross-wire), so it is served null instead of a physically-impossible number.\n- ``reason=\"prior_scale\"`` (#3242) — the release's prior-year figure for revenue,\n  net income or operating income is more than 10x anything the company has filed\n  for that line AND larger than any figure in the standard revenue and income\n  lines of its XBRL filings (a probable units error — a table in thousands read as\n  dollars), so the metric, current period included, is served null. Runs for every\n  company, not just the serve-cap's confirmed set.\n- ``reason=\"cash_flow_scale_revenue\"`` — the block's largest current operating cash\n  flow, free cash flow or capex figure is over $2B and at least 20x the revenue the\n  same release reports (80x for a block that is not the quarter alone), and larger\n  than anything the company has filed, so the whole cash-flow block is served null.\n  Rows stored before the earnings-release extractor checked this were never\n  re-checked (GLOP-PA served free cash flow $70.00B beside revenue of $89.5M). Runs\n  for every company. Any other ``cash_flow_scale_*`` reason is a further arm of the\n  same check, withholding the same block on different evidence; each arm's rule and\n  note live with it in ``serve_cap.CASH_FLOW_SCALE_ARMS``.\n- ``reason=\"currency_unverified\"`` (#2615) — the company reports in a currency\n  other than USD, and the earnings-release extraction does not yet record the\n  currency of each extracted figure, so the value cannot honestly be rendered as a\n  dollar amount (SONY's ¥2,837.77B was served as \"$2837.77B\").\n- ``reason=\"extractor_conflict\"`` — the release's results exist only as images of\n  its pages, and the two readings of them (v3 and legacy) disagree on this figure\n  beyond rounding, so neither is served; a margin computed from such a figure is\n  withheld with it. On the six such releases measured, v3-first served 10 wrong\n  headline figures; withholding the disagreements leaves 3. The same reason is used\n  for a release where one reading put a headline metric's quarters in opposite\n  columns (r108; NBIS Q2 FY2026 served its prior-year revenue as the quarter's);\n  its note says so.\n- ``reason=\"image_transcription_unreconciled\"`` — the same kind of release on the\n  overview card, which reads one extraction and cannot run that cross-check, so\n  its headline figures are withheld there; the earnings history serves the\n  reconciled ones.\n- ``reason=\"margin_implausible\"`` — the value is a margin outside the range a\n  margin can take (|value| > 1000%), so it is a unit or basis error rather than a\n  real ratio (DaVita served 7,467.38%). Needs no XBRL anchor, so it reaches filings\n  the serve-cap's confirmed set does not. ⚠ The bound is deliberately blunt and it\n  over-suppresses: a pre-revenue issuer with $0.28M of revenue and a $127M loss\n  genuinely has a margin of -44,760% and loses it too. Sparing that case by\n  checking the margin against its own operands does NOT work — BBDC's 44,408% is a\n  1000x scale error that reconciles just as exactly. The operands themselves are\n  always still served.\n- ``reason=\"net_income_sign_conflict\"`` — the net income has the opposite sign to\n  the net margin the same release reports, and it was read by the legacy\n  extractor's income-statement table reader, which takes a column by header\n  position and a row by first keyword match: QMLS served its prior-year $12.1M\n  profit beside a correct -339.3% margin. All 32 such figures measured were wrong\n  against XBRL. The quarterly pair and its growth are withheld; the margin is\n  served. Where the net income came from a model's reading, the same\n  contradiction was the margin's fault as often as not, so it does not fire.\n- ``reason=\"table_reader_implausible\"`` (r121) — the figure is the quarterly pair the\n  legacy extractor's income-statement table reader produced, and it cannot be the\n  release's figure for the line: an operating or net income under $10K beside revenue\n  of $10M or more (GL's per-share 4.84 read as $4,840; TROW's dash as $0.00), a\n  negative revenue (EXR's -$230.0M), or a revenue below a positive net income and at\n  least 20x below the largest revenue the company has filed (FIBK's $16.7M fee line;\n  MSTR's real $125.4M beside a $19.5B gain is 4.7x below and serves). A revenue arm\n  stands only when v3's own reading of the release does not corroborate the figure\n  (JXN's real $168.0M, a variable-annuity writer's revenue net of hedge losses, is\n  spared that way). Graded against the company's own XBRL over every firing in the\n  stored rows, JXN's was the only correct figure. The pair and its growth are\n  withheld; a slot v3 read itself still serves.\n- ``reason=\"segment_scale_mismatch\"`` (#3363 r88) — the release's top-level segment\n  amounts add up to 10^3 or 10^6 times the revenue the company filed for the quarter,\n  while the release's own headline revenue (when it has one) agrees with the filing:\n  so the amounts do not reconcile with the filing: a units error in reading the\n  segment table (HAIN served $263K against a filed $263.1M), or rows that are not\n  revenue at all (IVR's portfolio balances). The segment amounts are withheld, and so is every growth rate the\n  release does not state itself (one computed from the misread table can be wrong:\n  HAIN North America -83.6% against a stated -46%); names are kept.\n\n- ``reason=\"period_misread\"`` / ``\"figure_misread\"`` (r110 / r111) — a 6-K figure\n  listed in ``data/earnings_period_misreads.json`` after a census against the filing:\n  read from another period's column, or not the company's own figure for the period\n  (printed nowhere for that line, one segment's, or EPS in cents served as dollars).\n  From r112 the earnings processor judges every 6-K figure itself (the figure gate):\n  the same two reasons, plus ``\"figure_unchecked\"`` for a figure printed only in a\n  column that names no single period, so it could not be checked.\n\nThese are HONESTY signals, not attestations — a field NOT listed here is not thereby\nverified. An empty list means nothing was withheld; a present entry names exactly\nwhich metric to distrust and points at the filing to check."
    },
    "src__models__earnings_insights__GuidanceItem": {
      "properties": {
        "metric": {
          "type": "string",
          "title": "Metric",
          "description": "Metric name (e.g., 'Revenue', 'EPS', 'Operating Margin')"
        },
        "period": {
          "type": "string",
          "title": "Period",
          "description": "Forward period (e.g., 'Q3 FY2025', 'FY2025')"
        },
        "low_estimate": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Low Estimate",
          "description": "Low end of guidance range"
        },
        "high_estimate": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "High Estimate",
          "description": "High end of guidance range"
        },
        "point_estimate": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Point Estimate",
          "description": "Single point estimate"
        },
        "qualitative": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Qualitative",
          "description": "Qualitative guidance text (e.g., 'expect strong growth')"
        }
      },
      "type": "object",
      "required": [
        "metric",
        "period"
      ],
      "title": "GuidanceItem",
      "description": "Forward-looking guidance provided by management.\n\nCan be quantitative (range or point estimate) or qualitative."
    }
  }
}