Codebook File Layouts

qualcode.ai guides contain categories, and every category has a category name and a category description. Imported files can express those fields in several shapes — from a simple two-column list up to a power-user file with an explicit Level column. This page is the reference for how those source-file layouts map into guide categories.

Two things matter

The importer reads two different signals. Columns say where the source file stores values that can become category names, category descriptions, or an explicit row role. Rows say what each line means: a category, a hierarchy group, or a visual heading that should be ignored.

Terms like Code, Label, and Description below are source-file column names. They are not extra fields in a qualcode coding guide.

How rows are classified

These rules are the same across the supported column layouts:

1. An explicit Level value wins when the file has one.
2. If the source file has a Code column and the row has a code value, the row becomes a category whose name is that code. Marker words in that row are treated as normal source text.
3. If a row has no code and contains a marker such as (Net) or (Sub net), it becomes a hierarchy row.
4. If the source file has a Code column and a row has neither a code nor a marker, it is treated as a decorative group.
5. If the source file has no Code column, ordinary unmarked rows become categories because the name-like source column becomes the category name.

Example: two-column hierarchy

This restaurant example has only Code and Label columns. It still imports as a hierarchy because some blank-code rows use marker text:

After import, decorative groups do not become categories and do not appear in category descriptions. Source rows with Code values use those values as category names, while the hierarchy is folded into category descriptions:

• 1 → Food: Tasty / well-prepared
• 3 → Food › Menu variety: Good variety / many choices
• 11 → Service: Friendly / attentive staff

Supported layouts

Once the row rules are clear, the layouts are just column shapes. All of them can be flat or hierarchical; the rows decide that part.

Layout A — Code & label

The smallest code-based source file: one column for the value that becomes the category name and one for the text that becomes part of the category description.

The source Code column becomes the category name; the source Label is folded into the category description. See Source-code columns become category names below for why.

Layout B — Code, label, description

For researchers who've already written longer definitions. Same shape as Layout A plus a third column that carries the full description.

If hierarchy rows are present, the source label and source description are folded under the hierarchy prefix in the category description (e.g. Food: Tasty — Positive comments about the food's flavour…) so context isn't lost.

Layout C — Name & description (no codes)

For qualitative researchers and anyone whose codebook is organised by concept rather than by number. With no source Code column, the Name column becomes the category name.

Marker rows still work here. A row named Food (Net) becomes a hierarchy row, while an ordinary row like Delivery speed complaints becomes a category.

Layout D — Explicit Level column

The power-user shape. Add a Level column with values net, subnet, code, or group (or leave it blank to let auto-detection take over for that row). In this source-file column, code means "this row is an assignable category." Level overrides every other heuristic, which is useful when you generate codebooks programmatically and don't want the parser guessing.

Marker reference

When you don't supply a Level column, the parser scans the non-ignored cells in each row for marker keywords. Matching is case-insensitive and accent-insensitive. Brackets are recommended because they make intent obvious; classic tags like Net and Sub net also work without brackets for legacy files.

Broader words such as network, section, parent, and branch should be used as explicit tags, for example (network), or placed in their own marker cell. That keeps ordinary labels like "Network speed" from being mistaken for hierarchy.

The wizard preview lets you correct any detected row type before importing, so you can promote a decorative group to a net or subnet if the marker was missing.

Source-code columns become category names

When a source Code column is present, the code string becomes the category name — not the label. So a row with code "12" and label "Other service" produces a category literally named 12, with the label folded into its category description as Service: Other service.

This is what market-research workflows depend on. Researchers and clients don't talk about a category by its text label — they talk about it by code ("add a banner for code 12"). Tab plans key off the code; deliverable spreadsheets use the code as a column header. Keeping the code as the canonical name preserves that workflow end-to-end.

Layout C is the exception: with no source code column, the Name column becomes the category name and nothing gets folded into it.

The "per-net Other" problem (and why hierarchy solves it)

Real codebooks frequently have multiple "Other" categories — one for each top-level dimension. Imagine a Food net with codes 1 (Tasty) and 2 (Other food), and a Service net with codes 11 (Friendly) and 12 (Other service). Two flat codes both labelled simply "Other" would be incoherent: which one belongs where?

Because the parser knows about hierarchy, each category description gets the parent prefix baked in: Food › Other food and Service › Other service. The two categories are now disjoint by topic — and when the LLM enriches descriptions, it sees that context too, so the enriched INCLUDES and EXCLUDES lists keep the two cleanly separated.

Round-trip integrity

When you download a guide, the export file uses Code, Description as its column headers. In that export, Code contains the category name and Description contains the category description. A re-import preserves both; numeric names ("1", "12") and short alphanumeric names ("INN-01", "Q1") survive unchanged.

Hierarchy travels along inside the category description prefix (Food › Texture: Crunchy), so even a flat-format re-import keeps look-alike categories from different branches disjoint. The export is a clean flat representation of the guide, not a reconstruction of the original workbook formatting or hierarchy rows.

What the preview catches

Step 3 of the import wizard is your safety net. Common things it surfaces:

• Source-column mapping — for example, two source columns both look like candidate category descriptions. Pick the right one from the dropdown.
• Hierarchy row detection — if your file has category hierarchies, check that group rows and category rows look right before importing.
• Unmarked empty-code rows — by default these are decorative groups and ignored. Promote them to Net or Subnet if they were meant as structural nodes.
• Category count over 1,000 — the wizard refuses oversized imports here, before any credits are reserved. Split the codebook into two guides if you genuinely need more.

Related

• Import & Export — the end-to-end workflow that uses these layouts
• Best Practices — designing categories that work well once imported
• Training Versions — for the separate workflow of uploading training examples