{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/bettermenu/json-schema/bettermenu-search-token-response-schema.json",
  "title": "SearchTokenResponse",
  "description": "Per-caller org search tokens, one independent entry per searchable collection.\n\n``entries`` carries a key only for each collection the caller is\nentitled to search — the client must not attempt to query a\ncollection missing from this map; each entry's own token will reject\nsuch a request even if the client tries.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/bettermenu-org-api-openapi.yml#/components/schemas/SearchTokenResponse",
  "properties": {
    "host": {
      "type": "string",
      "title": "Host",
      "description": "Typesense host to connect to directly."
    },
    "port": {
      "type": "integer",
      "title": "Port",
      "description": "Typesense port to connect to directly."
    },
    "protocol": {
      "type": "string",
      "title": "Protocol",
      "description": "Typesense connection protocol (e.g. 'https')."
    },
    "entries": {
      "additionalProperties": {
        "$ref": "#/$defs/SearchTokenEntry"
      },
      "type": "object",
      "title": "Entries",
      "description": "One entry per collection the caller is entitled to search — keys are a subset of {'recipes', 'ingredients', 'ingredients_library', 'usda_ingredients', 'usda_bf_products'}. 'ingredients' and 'ingredients_library' mint against the same collection; only 'ingredients' excludes draft/archived status."
    },
    "routing_fields": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Routing Fields",
      "description": "Keys that may appear inside `query` but must NOT be forwarded to Typesense. They select between other keys rather than being query parameters, so sending one is a rejected search. A client that reads this needs no release when the set changes."
    }
  },
  "type": "object",
  "required": [
    "host",
    "port",
    "protocol",
    "entries"
  ],
  "$defs": {
    "SearchTokenEntry": {
      "properties": {
        "token": {
          "type": "string",
          "title": "Token",
          "description": "Scoped Typesense search token restricted to exactly `collection` and to documents matching this entry's own ACL."
        },
        "collection": {
          "type": "string",
          "title": "Collection",
          "description": "Exact Typesense collection name to query."
        },
        "expires_at": {
          "type": "integer",
          "title": "Expires At",
          "description": "Unix epoch seconds after which Typesense rejects this token."
        },
        "query": {
          "$ref": "#/$defs/SearchTokenQueryDescriptor",
          "description": "Query parameters the browser must pass to Typesense with this token."
        }
      },
      "type": "object",
      "required": [
        "token",
        "collection",
        "expires_at",
        "query"
      ],
      "title": "SearchTokenEntry",
      "description": "One collection's scoped token, its name, and how to query it.\n\n``token`` is independently minted for this entry alone — it is\nrestricted to exactly ``collection`` and rejects any request against a\ndifferent collection, regardless of what other entries appear in the\nsame response."
    },
    "SearchTokenQueryDescriptor": {
      "properties": {
        "query_by": {
          "type": "string",
          "title": "Query By",
          "description": "Typesense field(s) to search text against."
        },
        "sort_by": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Sort By",
          "description": "Typesense sort clause to apply to results."
        },
        "num_typos": {
          "type": "integer",
          "title": "Num Typos",
          "description": "Maximum typo tolerance for the search query."
        },
        "prefix": {
          "type": "boolean",
          "title": "Prefix",
          "description": "Whether to match the query text as a prefix (typeahead)."
        },
        "per_page": {
          "type": "integer",
          "title": "Per Page",
          "description": "Number of results to return per page."
        },
        "query_by_weights": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Query By Weights",
          "description": "Per-field weighting for query_by, comma-separated."
        },
        "include_fields": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Include Fields",
          "description": "Comma-separated fields to include in results."
        },
        "highlight_fields": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Highlight Fields",
          "description": "Comma-separated fields to highlight matches in."
        },
        "prioritize_exact_match": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Prioritize Exact Match",
          "description": "Whether an exact match should rank first."
        },
        "drop_tokens_mode": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Drop Tokens Mode",
          "description": "Which end of the query Typesense drops tokens from when it must drop any. English food names put the head noun last, so the Typesense default (right_to_left) discards the word that matters."
        },
        "single_token_sort_by": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Single Token Sort By",
          "description": "Sort clause to use INSTEAD OF `sort_by` when the query is a single token. A one-word query scores every match identically, so the tiebreak chain decides the result there and nowhere else, and the chain that helps one word measurably hurts several. Null means no routing: keep using `sort_by` for every query."
        },
        "single_token_num_typos": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Single Token Num Typos",
          "description": "Typo tolerance to use INSTEAD OF `num_typos` when the query is a single token. Raising it is safe for one word but not in general (`unsalted` is two edits from `salted`). Null means no routing."
        }
      },
      "type": "object",
      "required": [
        "query_by",
        "num_typos",
        "prefix",
        "per_page"
      ],
      "title": "SearchTokenQueryDescriptor",
      "description": "How the browser must query one collection with its own scoped token.\n\nMirrors the query fields the server-side executor for that same\ncollection uses, so the browser never hardcodes its own search\nbehavior. Fields beyond ``query_by``/``num_typos``/``prefix``/\n``per_page`` are optional — the org-scoped recipes/ingredients entries\ndon't set them, while the standard-collection entries do (mirroring\n``TypesenseSearchProvider.SEARCH_CONFIG``/``COLLECTION_CONFIG``).\n``sort_by`` is optional because the standard ``usda_bf_products``\ncollection deliberately has none."
    }
  }
}