{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/3gppscout-com/json-schema/3gppscout-com-text-search-request-schema.json",
  "title": "TextSearchRequest",
  "description": "Request body for text search.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/3gppscout-com-openapi.json#/components/schemas/TextSearchRequest",
  "properties": {
    "query": {
      "type": "string",
      "title": "Query",
      "description": "Natural language search query. Be specific — e.g. 'RRC connection reconfiguration procedure' rather than just 'RRC'."
    },
    "match_count": {
      "type": "integer",
      "maximum": 200.0,
      "minimum": 1.0,
      "title": "Match Count",
      "description": "Candidate matches to retrieve before reranking. Higher = slower but more thorough. Default 30 balances speed and quality.",
      "default": 30
    },
    "match_threshold": {
      "type": "number",
      "maximum": 1.0,
      "minimum": 0.0,
      "title": "Match Threshold",
      "description": "Minimum similarity score. Leave at 0 (default) and rely on reranking for quality filtering.",
      "default": 0.0
    },
    "rerank": {
      "type": "boolean",
      "title": "Rerank",
      "description": "Rerank results for higher precision. Always leave true (default) — the reranker dramatically improves result quality.",
      "default": true
    },
    "rerank_top_k": {
      "type": "integer",
      "maximum": 50.0,
      "minimum": 1.0,
      "title": "Rerank Top K",
      "description": "Number of final results after reranking. Use 3–5 for focused lookups, 10–20 for broad research.",
      "default": 10
    },
    "include_section_text": {
      "type": "boolean",
      "title": "Include Section Text",
      "description": "Include the full parent section text alongside each chunk. Provides richer context but increases response size.",
      "default": true
    },
    "deduplicate": {
      "type": "boolean",
      "title": "Deduplicate",
      "description": "Collapse near-duplicate results from different releases/versions (same doc_number + section_number), so rerank_top_k counts distinct sections. Keeps the highest-scored result (the newest release when scores tie, as identical text across releases does) and annotates it with an 'also_in' list showing each collapsed match's release, version, and scores. Ignored when filter_release is set.",
      "default": true
    },
    "filter_release": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Filter Release",
      "description": "Restrict to a specific 3GPP release. Examples: 'Rel-15', 'Rel-17', 'Rel-20'. Omit for all indexed releases (Rel-15 through Rel-20)."
    },
    "filter_doc_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Filter Doc Type",
      "description": "Restrict by document type: 'TS' (Technical Specification) or 'TR' (Technical Report). Omit for both."
    },
    "filter_doc_number": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Filter Doc Number",
      "description": "Restrict to a specific document, e.g. '38.331' (NR RRC), '23.501' (system architecture), '38.300' (NR overview). Use the numeric format without the 'TS'/'TR' prefix."
    },
    "filter_series": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Filter Series",
      "description": "Restrict by 3GPP series number: '38' = NR/5G radio, '23' = system architecture, '24' = signalling, '36' = LTE, '33' = security, '29' = core network."
    },
    "filter_section_number": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Filter Section Number",
      "description": "Restrict to a specific section, e.g. '5.3.5'. Only useful when combined with filter_doc_number."
    },
    "prefer_latest": {
      "type": "boolean",
      "title": "Prefer Latest",
      "description": "Add latest_version and latest_release (the newest indexed version of the document) to each result, and when deduplicating keep the newest matched version of each section instead of the highest-scored one.",
      "default": false
    },
    "available_before": {
      "anyOf": [
        {
          "type": "string",
          "format": "date"
        },
        {
          "type": "null"
        }
      ],
      "title": "Available Before",
      "description": "Only versions uploaded to the 3GPP archive before this date (YYYY-MM-DD; before 00:00 UTC, so the day itself is excluded), e.g. a patent application's priority date. A version whose upload time is unknown is left out. Usually one version per release of each spec is indexed (the newest in that release, Rel-15 onward), so a release appears only if that version predates the cutoff; older versions are in the 3GPP archive but not searchable here."
    },
    "include_children": {
      "type": "boolean",
      "title": "Include Children",
      "description": "Add each result's sub-clauses (number, title, token count; all of them up to 12, else the direct ones) and descendant_count, so you can pick the clause to read without a table-of-contents call.",
      "default": false
    }
  },
  "type": "object",
  "required": [
    "query"
  ]
}