{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/edgechat-ai/json-schema/edgechat-ai-search-response-schema.json",
  "title": "SearchResponse",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/edgechat-ai-search-api-openapi.yml#/components/schemas/SearchResponse",
  "allOf": [
    {
      "type": "object",
      "properties": {
        "query": {
          "type": "string"
        },
        "did_you_mean": {
          "type": "string"
        },
        "topics": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Topic"
          },
          "description": "On page 1, when the words name a topic ('science fiction writers'): that topic. Its articles are at its `api_url`; a title search finds few of them."
        },
        "total": {
          "type": "integer"
        },
        "page": {
          "type": "integer"
        },
        "pages": {
          "type": "integer"
        },
        "results": {
          "type": "array",
          "description": "Title, alias, and misspelling matches first; when no title shares a word with the query, articles whose text matches follow (match: fulltext), counted in total and pages and never repeated across pages.",
          "items": {
            "allOf": [
              {
                "$ref": "#/$defs/ArticleSummary"
              },
              {
                "$ref": "#/$defs/SearchResultAdditions"
              },
              {
                "$ref": "#/$defs/DerivedFields"
              }
            ]
          }
        },
        "license": {
          "$ref": "#/$defs/License"
        }
      }
    },
    {
      "$ref": "#/$defs/SearchAnswerAdditions"
    }
  ],
  "$defs": {
    "ArticleSummary": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "slug": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "topic": {
          "type": [
            "string",
            "null"
          ],
          "description": "The top-level branch of the topic tree the article is under. Its own topic is the last entry of the article's `topic_path`."
        },
        "excerpt": {
          "type": "string",
          "description": "The corpus snippet when available, otherwise the article opening as plain text. Older listing excerpts may end in an ellipsis (…)."
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "markdown_url": {
          "type": "string",
          "format": "uri"
        },
        "api_url": {
          "type": "string",
          "format": "uri"
        },
        "snippet": {
          "type": "string",
          "description": "Optional corpus-authored summary, separate from the article opening. Present on corpus-v1.5 articles and their preview results."
        },
        "node": {
          "type": "string",
          "description": "Current concept-tree node of the article, when available. May change when the corpus tree is revised."
        }
      },
      "required": [
        "id",
        "slug",
        "title",
        "excerpt",
        "url",
        "markdown_url",
        "api_url"
      ]
    },
    "DerivedFields": {
      "type": "object",
      "description": "On search results and articles (api/_derived.js through the fetch and search options).",
      "properties": {
        "importance": {
          "type": "number",
          "description": "0 to 1; PageRank over the in-text links, as a percentile. A link count, not a judgment."
        },
        "rank": {
          "type": "integer",
          "description": "1 = most central"
        },
        "words": {
          "type": "integer"
        },
        "reading_grade": {
          "type": "number",
          "description": "Flesch-Kincaid grade"
        },
        "reading_minutes": {
          "type": "integer"
        },
        "match": {
          "type": "string",
          "enum": [
            "fulltext"
          ],
          "description": "On a result found in the articles' text (BM25) because no title or alias matched."
        }
      }
    },
    "License": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "summary": {
          "type": "string"
        },
        "spdx": {
          "type": "string"
        }
      },
      "required": [
        "name",
        "url"
      ]
    },
    "Match": {
      "type": "string",
      "enum": [
        "exact",
        "alias",
        "misspelling",
        "partial",
        "none",
        "fulltext"
      ]
    },
    "SearchAnswerAdditions": {
      "type": "object",
      "properties": {
        "match": {
          "$ref": "#/$defs/Match"
        },
        "searched_as": {
          "type": "string",
          "description": "The transliterated query that ran, when the query as typed found nothing."
        },
        "scope": {
          "type": "string"
        },
        "facets": {
          "type": "object",
          "properties": {
            "topic": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "label": {
                    "type": "string"
                  },
                  "count": {
                    "type": "integer"
                  },
                  "api_url": {
                    "type": "string"
                  }
                }
              }
            },
            "geo": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "label": {
                    "type": "string"
                  },
                  "count": {
                    "type": "integer"
                  },
                  "api_url": {
                    "type": "string"
                  }
                }
              }
            },
            "counted": {
              "type": "object",
              "properties": {
                "topic": {
                  "type": "integer"
                },
                "geo": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "SearchResultAdditions": {
      "type": "object",
      "properties": {
        "match": {
          "$ref": "#/$defs/Match"
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "A fixed rule, not a calibrated probability (see /developers)."
        },
        "highlight": {
          "type": "string",
          "description": "The sentence of the summary or opening holding the most query words."
        }
      }
    },
    "Topic": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "label": {
          "type": "string"
        },
        "articles": {
          "type": "integer"
        },
        "api_url": {
          "type": "string",
          "format": "uri"
        }
      },
      "required": [
        "id",
        "label",
        "api_url"
      ]
    }
  }
}