{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/metricduck-com/json-schema/metricduck-com-filing-text-response-schema.json",
  "title": "FilingTextResponse",
  "description": "Response containing text chunks.",
  "x-generated": "2026-11-18",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/metricduck-com-openapi.json#/components/schemas/FilingTextResponse",
  "properties": {
    "total_results": {
      "type": "integer",
      "title": "Total Results"
    },
    "results": {
      "items": {
        "$ref": "#/$defs/FilingTextChunk"
      },
      "type": "array",
      "title": "Results"
    },
    "query": {
      "$ref": "#/$defs/FilingTextRequest"
    },
    "execution_time_ms": {
      "type": "number",
      "title": "Execution Time Ms"
    },
    "bytes_processed": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Bytes Processed"
    },
    "keyword_matched": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Keyword Matched",
      "description": "True when the supplied keyword matched ≥1 row. False when the service fell back to returning the full section because the keyword matched zero rows. None when no keyword was supplied. Callers (e.g. MCP tools) should annotate the response when False so the caller knows the content is a broader browse view, not a keyword hit."
    },
    "keyword_relaxed": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Keyword Relaxed",
      "description": "True when keyword_matched is False AND the no-exact-match browse fallback was RANKED + TRIMMED to the few chunks with the most keyword-token overlap (graded degradation), rather than dumping the full section. Lets callers annotate 'showing the N most relevant chunks' instead of 'showing the full section'. None/absent otherwise."
    },
    "keyword_total_matches": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Keyword Total Matches",
      "description": "How many chunks of the pinned section matched the keyword, before pagination; `results` is one page of those matches, in filing order, and `offset` indexes the list of matches. 0 on a keyword miss. None when no keyword was supplied or the request was not pinned to one section of one filing (no total)."
    },
    "keyword_ranked_of": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Keyword Ranked Of",
      "description": "On a keyword miss (keyword_matched False) pinned to one section of one filing: how many of the section's chunks were ranked by term overlap to pick the closest (every chunk, up to the 500 cap). `results` is a page of those closest, in filing order; a page past them is empty with this still set (the end of the close matches, not a miss). None otherwise."
    },
    "keyword_best_overlap": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Keyword Best Overlap",
      "description": "Set with keyword_ranked_of: how many of the keyword's terms the closest chunk holds. 0 means no chunk holds any term, so the chunks served are the section's first, not close to anything. None otherwise."
    },
    "keyword_presence": {
      "anyOf": [
        {
          "$ref": "#/$defs/KeywordPresenceResponse"
        },
        {
          "type": "null"
        }
      ],
      "description": "#582, inline: when keyword_matched is False, which of the SERVED filing's sections contain the keyword -- the same probe as /filings/sections/keyword-presence, run alongside the browse fallback so the caller needs no second request. None when the keyword matched or no single served filing was probed."
    },
    "latest_filing": {
      "anyOf": [
        {
          "$ref": "#/$defs/LatestFilingHint"
        },
        {
          "type": "null"
        }
      ],
      "description": "Latest filing of the resolved form type for the company. Populated when the service resolved a 'latest' filing for the request (i.e. no accession_number was supplied). Lets callers detect when results come from an older filing (e.g. when the requested section is not present in the latest filing and no fallback was possible)."
    },
    "section_fallback": {
      "anyOf": [
        {
          "$ref": "#/$defs/SectionFallback"
        },
        {
          "type": "null"
        }
      ],
      "description": "Populated when the requested section was not present in the latest filing and the service auto-fell-back to a related section on the same latest filing (currently: MD&A subsections → mda_full). Callers should surface this note in the rendered response so users see what was actually served."
    },
    "served_filing": {
      "anyOf": [
        {
          "$ref": "#/$defs/LatestFilingHint"
        },
        {
          "type": "null"
        }
      ],
      "description": "The filing actually served (accession, filing_date, form_type). Populated on non-empty resolutions so callers see the VINTAGE of what they received — critical when vantage_date was applied or when the latest filing predates the caller's 'now'. Distinct from latest_filing (the newest filing of that form for the company)."
    },
    "vantage_date": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Vantage Date",
      "description": "Echo of the as-of vantage applied to this request (ISO date), or None."
    },
    "vantage_applied": {
      "type": "boolean",
      "title": "Vantage Applied",
      "description": "True when a vantage_date upper-bound constrained filing resolution.",
      "default": false
    },
    "unextracted_period": {
      "items": {
        "$ref": "#/$defs/UnextractedPeriodFiling"
      },
      "type": "array",
      "title": "Unextracted Period",
      "description": "#582: on an EMPTY response, the filing(s) the XBRL DEI period index (or earnings-8K period derivation) resolved for the requested company/period whose section TEXT was not extracted. NON-EMPTY ⇒ State B (in MetricDuck's scope, text pending — the reported numbers ARE in XBRL; pivot to get_financials/get_xbrl_facts). EMPTY on an otherwise-empty response ⇒ State C (no XBRL period record — terminal 'not retrievable here'). Best-effort: absent when the probe is inapplicable (no fiscal_year/period requested) or errors."
    },
    "cross_section_keyword": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Cross Section Keyword",
      "description": "#582: when a keyword matched no chunk in the requested section, the parent_section_ids of THIS filing whose text DOES contain the keyword (same stemming as the per-section match). Empty list ⇒ the term appears in NONE of the filing's servable sections (decisive absence). None ⇒ the cross-section probe did not run (no keyword fallback). Best-effort/optional."
    },
    "qa_split": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "ir_lead",
            "marker"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Qa Split",
      "description": "r102: set when transcript_qa_session was served by splitting the call's stored prepared remarks at read time (most transcripts store the whole call as prepared remarks): 'ir_lead' = cut at the transcript IR's first Q&A turn, 'marker' = cut at the acquirer's Q&A marker (a Q&A header, the operator's hand-off or the first question). None when real qa_session rows (or the IR's text) were served."
    },
    "transcript_present": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Transcript Present",
      "description": "r102: on an EMPTY transcript_qa_session response, True when the call's transcript IS stored (accession in transcript_accession) but its Q&A could not be separated from the prepared remarks, which then hold the whole call. None otherwise."
    },
    "transcript_accession": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Transcript Accession",
      "description": "r102: the accession whose transcript is stored, when transcript_present."
    }
  },
  "type": "object",
  "required": [
    "total_results",
    "results",
    "query",
    "execution_time_ms"
  ],
  "$defs": {
    "FilingTextChunk": {
      "properties": {
        "chunk_id": {
          "type": "string",
          "title": "Chunk Id"
        },
        "ticker": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Ticker"
        },
        "cik": {
          "type": "string",
          "title": "Cik"
        },
        "company_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Company Name"
        },
        "accession_number": {
          "type": "string",
          "title": "Accession Number"
        },
        "form_type": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Form Type"
        },
        "filing_date": {
          "type": "string",
          "title": "Filing Date"
        },
        "fiscal_year": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Fiscal Year"
        },
        "fiscal_period": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Fiscal Period"
        },
        "section_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Section Id"
        },
        "parent_section_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Parent Section Id"
        },
        "section_display_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Section Display Name"
        },
        "category": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Category"
        },
        "content_text": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Content Text"
        },
        "content_raw": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Content Raw"
        },
        "text_chars": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Text Chars"
        },
        "text_words": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Text Words"
        },
        "token_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Token Count"
        },
        "chunk_index": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Chunk Index"
        },
        "total_chunks": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Total Chunks"
        },
        "extraction_strategy": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Extraction Strategy"
        },
        "xbrl_concept_found": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Xbrl Concept Found"
        },
        "extracted_at": {
          "type": "string",
          "title": "Extracted At"
        },
        "sec_edgar_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Sec Edgar Url"
        },
        "section_anchored": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Section Anchored"
        },
        "viewer_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Viewer Url"
        },
        "source_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Source Url"
        },
        "transcript_source": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Transcript Source"
        },
        "accounting_standard": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Accounting Standard"
        },
        "table_json": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Table Json"
        },
        "table_caption": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Table Caption"
        },
        "table_rows": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Table Rows"
        },
        "table_cols": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Table Cols"
        },
        "deferred_to": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Deferred To"
        }
      },
      "type": "object",
      "required": [
        "chunk_id",
        "cik",
        "accession_number",
        "filing_date",
        "extracted_at"
      ],
      "title": "FilingTextChunk",
      "description": "Single text chunk from a filing. Supports chunk, section, and table row types."
    },
    "FilingTextRequest": {
      "properties": {
        "ticker": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 10
            },
            {
              "type": "null"
            }
          ],
          "title": "Ticker",
          "description": "Company ticker symbol"
        },
        "cik": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{10}$"
            },
            {
              "type": "null"
            }
          ],
          "title": "Cik",
          "description": "10-digit CIK"
        },
        "accession_number": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{10}-\\d{2}-\\d{6}$"
            },
            {
              "type": "null"
            }
          ],
          "title": "Accession Number"
        },
        "section_id": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 128,
              "pattern": "^[a-z0-9_]+$"
            },
            {
              "type": "null"
            }
          ],
          "title": "Section Id",
          "description": "Section filter (canonical IDs + header-derived sub-section IDs from list_filings)"
        },
        "form_type": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "10-K",
                "10-Q",
                "10-K/A",
                "10-Q/A",
                "8-K",
                "DEF 14A",
                "20-F",
                "20-F/A",
                "40-F",
                "40-F/A",
                "6-K",
                "6-K/A"
              ]
            },
            {
              "type": "null"
            }
          ],
          "title": "Form Type",
          "description": "SEC form type"
        },
        "from_date": {
          "anyOf": [
            {
              "type": "string",
              "format": "date"
            },
            {
              "type": "null"
            }
          ],
          "title": "From Date",
          "description": "Start date (inclusive)"
        },
        "to_date": {
          "anyOf": [
            {
              "type": "string",
              "format": "date"
            },
            {
              "type": "null"
            }
          ],
          "title": "To Date",
          "description": "End date (inclusive)"
        },
        "fiscal_year": {
          "anyOf": [
            {
              "type": "integer",
              "maximum": 2100.0,
              "minimum": 2000.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Fiscal Year"
        },
        "fiscal_period": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "Q1",
                "Q2",
                "Q3",
                "FY"
              ]
            },
            {
              "type": "null"
            }
          ],
          "title": "Fiscal Period",
          "description": "Fiscal period"
        },
        "vantage_date": {
          "anyOf": [
            {
              "type": "string",
              "format": "date"
            },
            {
              "type": "null"
            }
          ],
          "title": "Vantage Date",
          "description": "As-of vantage (point-in-time): resolve the latest filing filed ON OR BEFORE this date instead of the newest. Omit for the latest filing. Filings filed after this date are excluded (filing_date <= vantage_date)."
        },
        "row_type": {
          "type": "string",
          "enum": [
            "chunk",
            "section",
            "table"
          ],
          "title": "Row Type",
          "description": "Content type",
          "default": "chunk"
        },
        "since": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ],
          "title": "Since",
          "description": "Filter by extracted_at >= timestamp (ISO 8601) for incremental sync"
        },
        "keyword": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 200,
              "minLength": 2
            },
            {
              "type": "null"
            }
          ],
          "title": "Keyword",
          "description": "Keyword filter — returns only chunks containing this text (case-insensitive)"
        },
        "limit": {
          "type": "integer",
          "maximum": 1000.0,
          "minimum": 1.0,
          "title": "Limit",
          "default": 100
        },
        "offset": {
          "type": "integer",
          "minimum": 0.0,
          "title": "Offset",
          "default": 0
        }
      },
      "type": "object",
      "title": "FilingTextRequest",
      "description": "Query parameters for filing text retrieval."
    },
    "KeywordPresenceResponse": {
      "properties": {
        "accession_number": {
          "type": "string",
          "title": "Accession Number"
        },
        "keyword": {
          "type": "string",
          "title": "Keyword"
        },
        "matched_sections": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Matched Sections",
          "description": "parent_section_ids of THIS filing whose chunk text contains the keyword (stemmed). Empty ⇒ absent in every servable section."
        },
        "all_sections": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "All Sections",
          "description": "The filing's servable section_ids (so the caller can name 'NONE of a, b, c…')."
        },
        "terms": {
          "type": "integer",
          "title": "Terms",
          "description": "How many independent terms the matcher ANDs, order-free (a compound such as '5.750%' or 'R&D' is one term). Lets the caller describe the match without re-tokenizing.",
          "default": 0
        }
      },
      "type": "object",
      "required": [
        "accession_number",
        "keyword",
        "matched_sections",
        "all_sections"
      ],
      "title": "KeywordPresenceResponse",
      "description": "#582: which of ONE filing's servable sections contain a keyword.\n\nPowers get_filing_section's decisive cross-section verdict — when a keyword\nmisses in the requested section, the worker asks here to say either \"it's in\nsibling X\" (one pivot) or \"it appears in NONE of these N sections\" (terminal\nabsence) instead of dumping ranked tangential chunks + a \"refine/browse\" nudge.\n`matched_sections` uses the SAME stemming as the per-section keyword filter, so\nthe verdict can never contradict the served browse."
    },
    "LatestFilingHint": {
      "properties": {
        "accession_number": {
          "type": "string",
          "title": "Accession Number"
        },
        "filing_date": {
          "type": "string",
          "title": "Filing Date"
        },
        "form_type": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Form Type"
        },
        "text_extracted": {
          "type": "boolean",
          "title": "Text Extracted",
          "default": true
        }
      },
      "type": "object",
      "required": [
        "accession_number",
        "filing_date"
      ],
      "title": "LatestFilingHint",
      "description": "Pointer to the latest filing of a given form type for a company.\n\nPopulated on latest-resolution paths so callers can detect when a section\nrequest was satisfied against a filing OTHER than the latest — previously\na silent failure mode that returned prior-year content under the\n`get_filing_section` contract."
    },
    "SectionFallback": {
      "properties": {
        "requested_section_id": {
          "type": "string",
          "title": "Requested Section Id"
        },
        "served_section_id": {
          "type": "string",
          "title": "Served Section Id"
        },
        "reason": {
          "type": "string",
          "title": "Reason"
        },
        "referenced_form": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Referenced Form"
        },
        "referenced_accession": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Referenced Accession"
        },
        "referenced_filing_date": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Referenced Filing Date"
        },
        "kind": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "incorporated_by_reference",
                "older_filing_served",
                "older_filing_withheld"
              ]
            },
            {
              "type": "null"
            }
          ],
          "title": "Kind"
        }
      },
      "type": "object",
      "required": [
        "requested_section_id",
        "served_section_id",
        "reason"
      ],
      "title": "SectionFallback",
      "description": "Populated when the requested section is absent from the latest filing\nand the service fell back to a related section on the SAME latest filing,\nOR when the latest filing's section is an incorporation-by-reference stub\nthat points the caller at a different filing.\n\nTriggers today:\n  - MD&A subsection missing from latest filing → served via `mda_full` on\n    the same filing (Candidate A fix).\n  - 10-Q section is incorporated-by-reference to 10-K (`deferred_to`\n    signal) → served as-is but with `referenced_form` + `referenced_\n    accession` pointing at the latest 10-K so callers can retrieve the\n    real content without guessing."
    },
    "UnextractedPeriodFiling": {
      "properties": {
        "accession_number": {
          "type": "string",
          "title": "Accession Number"
        },
        "form_type": {
          "type": "string",
          "title": "Form Type"
        },
        "filing_date": {
          "type": "string",
          "title": "Filing Date",
          "default": ""
        },
        "fiscal_year": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Fiscal Year"
        },
        "fiscal_period": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Fiscal Period"
        }
      },
      "type": "object",
      "required": [
        "accession_number",
        "form_type"
      ],
      "title": "UnextractedPeriodFiling",
      "description": "A filing that EXISTS in MetricDuck's XBRL DEI period index (or, for an\nearnings 8-K, resolves via the deterministic period derivation) but whose\nrequested section TEXT was not extracted into filing_text_sections.\n\n#582: attached to an EMPTY get_filing_section response so the MCP can tell\nState B (in-scope, text pending — pivot to XBRL/get_financials, the numbers\nARE there) from State C (no XBRL period record at all — terminal \"not in\nMetricDuck\"). Distinct from routes.filing_text.UnextractedFiling (the\nlist_filings analog) so the get_text response model stays self-contained."
    }
  }
}