FAQ Data Management and Search Index with JSON + KV

Introduction

When building an FAQ in-house, the first thing to decide is "how to hold the data."
How lightly you can build this dramatically changes how easy operations will be afterward.

In this article, I explain the per-category JSON + Vercel KV structure I adopted for an apparel and gear EC site, and how to build the search index that powers cross-category search. It's not enough to warrant a full database, but plain text makes search weak — this design threads that needle.

Holding Data as Per-Category JSON

One File per Category

The FAQ spans about ten categories and 100-plus questions. Bundling all of that into one giant file means touching the whole thing on every edit, and diffs become hard to read. So I split it into one JSON file per category — units like "Shipping & Delivery," "Returns & Exchanges," and "Account Registration." To add a category, you just add a file. Because the impact of an edit is closed at the file level, conflicts are rare even when several people are editing.

The Minimal Structure for One Question

A single FAQ is represented with the minimum of fields: question, answer, and display order. The point is to keep it deliberately simple rather than an elaborate schema. Allowing light links and formatting in the answer while keeping the structure flat makes both admin-UI editing and Git diff review straightforward.

Why JSON Is Enough at First

Honestly, "a database for something like an FAQ" feels overkill. The count is in the hundreds and updates aren't that frequent. With JSON you get version control for free through Git, leaving a history of when, who, and what changed. There's none of the schema-migration overhead of a relational DB, and it runs perfectly well this way to start.

Syncing with Vercel KV for Fast Delivery

JSON Is the Truth, KV Handles Delivery

JSON is great for management, but reading and parsing a file on every request is inefficient for delivery. So I hold JSON as the source of truth while serving production display from a fast key-value store (Vercel KV) — a two-tier setup. When JSON is updated, it's synced to KV, and what users see is always the KV data. You give up neither ease of management nor display speed.

Designing Keys per Category

Data is stored in KV per category. When a category page opens, being able to fetch just that category's FAQs in one shot is all you need. There's no need to read every FAQ at once each time — you pull only what's required, with no waste.

The Search Index Behind Cross-Category Search

Letting Users Search Across Categories

Splitting the FAQ by category makes management easy, but users don't know which category their question belongs to. They want to look up "refund" but aren't sure if it lives under "Returns & Exchanges" or "Payments." So I separately generate a search index (search-index) consolidating the FAQs of every category, enabling cross-category search. Users search by words alone, without thinking about categories.

Light Preprocessing to Improve Hit Rate

The search index indexes the question and answer bodies together. Layering in light normalization to absorb notation variations (unifying full-width and half-width characters, and the like) improves the hit rate. Without standing up an elaborate full-text search engine, this much preprocessing is enough to deliver a "what you typed gets found" experience. The index itself also sits in KV and returns candidates inline as you type.

Conclusion

The FAQ data design rests on three points: holding per-category JSON as the source of truth, serving delivery from Vercel KV, and running cross-category search from a pre-generated search index. It's not enough for a database, but smarter than plain text. That balance is just right for an FAQ in the hundreds.

How this data is edited, synced, and operated is covered in Admin-UI Editing with Git-Based Sync. For the full picture, see Building an In-House FAQ System.