Skip to main content
v2026.11,986 entries · CC-BY 4.0

Codebook: What It Is, What Goes in One, and How to Build One

What a codebook is in quantitative and qualitative research, what fields each type contains, and a step-by-step process for building one, with worked examples.

Written and maintained by CASRAI Editorial Board

Published · Last updated

On this page

A codebook is the reference document that tells you (or anyone else) exactly what each piece of data in a study means and how it was assigned. In quantitative research it maps every variable to its possible values; in qualitative research it maps every code to the meaning, boundaries, and example text that justify applying it. The two traditions share a name and a purpose — making analysis transparent and repeatable — but the document itself looks different in each.

Codebook meaning: the short answer

A codebook is a structured record that defines the coding scheme used to turn raw data into analyzable data. It exists so that a second researcher — or the same researcher six months later — can look at a variable or a code and know precisely what it represents, without having to guess or re-derive the logic. Every codebook, regardless of discipline, answers the same underlying question: what does this label actually mean, and how do I know when it applies?

The term splits into two related but distinct uses:

  • Quantitative codebook (also called a data codebook or variable codebook): documents every variable in a dataset — its name, label, permitted values, and missing-value conventions. This is the sense used by data archives such as ICPSR and the General Social Survey (GSS), where the codebook ships alongside the dataset itself.
  • Qualitative codebook: documents every code used to label segments of text (interview transcripts, field notes, open-ended survey responses) — its definition, inclusion and exclusion criteria, and an example of text that illustrates it.

If you only need the short version: a codebook is the key that makes your data legible to someone who wasn’t in the room when you collected or coded it.

The quantitative codebook: anatomy and example

A quantitative codebook is built around variables, not cases. For each variable in a dataset, it records enough detail that someone with only the codebook and the raw data file could reconstruct what every value means. The core elements are:

  • Variable name — the short machine-readable identifier used in the dataset (e.g., a column header).
  • Variable label — a plain-language description of what the variable measures.
  • Value codes and value labels — the numeric or categorical codes used in the data, and what each one means (e.g., 1 = Yes, 2 = No).
  • Missing-value conventions — how non-responses, skips, and refusals are distinguished from one another (e.g., -99 = Not applicable, -98 = Refused, -97 = Don't know).
  • Data type and format — whether the variable is numeric, string, date, or categorical, and any formatting rules.
  • Source or derivation note — whether the variable was collected directly (e.g., from a survey item) or computed from other variables, and if so, how.

An illustrative example of a single entry from a survey codebook:

Field Entry
Variable name Q14_EMPSTAT
Variable label Current employment status
Value codes 1 = Employed full-time; 2 = Employed part-time; 3 = Unemployed, looking; 4 = Not in labor force
Missing values -98 = Refused; -99 = Not asked (skip pattern)
Data type Categorical (integer)
Source Directly collected, survey item Q14

This is the sense of “codebook” used when researchers ask for a codebook for quantitative research: it is documentation for the dataset, not an analytical framework. It is closely related to, but not identical to, a data dictionary — see the comparison below.

The qualitative codebook: anatomy and example

A codebook in qualitative research documents the coding scheme applied to text data during analysis — for example, in thematic analysis, content analysis, or grounded theory. Rather than describing variables, it describes codes: the labels a researcher applies to meaningful segments of text. A well-built qualitative codebook typically includes:

  • Code name — a short, consistent label for the concept.
  • Definition — what the code means, written precisely enough that two coders would apply it the same way.
  • Inclusion criteria — the conditions under which the code should be applied.
  • Exclusion criteria — text that looks similar but should NOT receive this code, and why.
  • Example quote — a real (or representative) excerpt that illustrates correct application.
  • Parent code / hierarchy position — where the code sits if the scheme is organized into themes and sub-codes.

An illustrative example of a single entry from a qualitative codebook:

Field Entry
Code name Access_Barrier_Cost
Definition Participant describes cost as a reason for not using or delaying use of a service.
Inclusion Any explicit reference to affordability, price, or inability to pay.
Exclusion General dissatisfaction with a service that does not mention cost (code instead as Access_Barrier_Quality).
Example quote “I would have gone back, but after the second visit I just couldn’t keep paying out of pocket.”
Parent code Access_Barrier (theme)

Qualitative codebooks are usually built and revised inside coding software such as NVivo, ATLAS.ti, or MAXQDA, but the codebook itself — as a document — is what makes the coding scheme auditable independent of any specific tool. For the mechanics of applying codes to transcripts, see coding qualitative interview data.

How to build a codebook: step by step

The process differs slightly by tradition, but both follow the same underlying logic: define categories, apply them consistently, and document disagreements or revisions.

Building a quantitative codebook

  1. List every variable in the dataset, in the order they appear.
  2. Assign a variable name and label for each — the name should be stable and machine-readable; the label should be human-readable.
  3. Enumerate value codes for every categorical or coded variable, including all possible response options.
  4. Define missing-value conventions up front and apply them consistently — distinguish “not asked” from “asked but refused” from “asked but skipped due to routing.”
  5. Document derived variables — if a variable is computed from others (e.g., an age band derived from a birth year), record the formula or rule.
  6. Version the codebook alongside the dataset — if variables change between data releases, the codebook needs its own version history.

Building a qualitative codebook

  1. Start with a provisional set of codes — drawn deductively from your research questions or theoretical framework, inductively from an initial read of the data, or both.
  2. Write a working definition for each code before coding the full dataset, not after.
  3. Pilot the codebook on a subset of the data with more than one coder where possible, and compare results.
  4. Refine definitions and boundaries based on disagreements — most codebook revisions happen because two coders applied a code differently, which usually means the definition was ambiguous.
  5. Add or split codes as new patterns emerge, and retire codes that turn out to be redundant or too broad to be useful.
  6. Freeze the codebook once it is stable, and apply it consistently to the remaining data — further changes at that point require re-checking previously coded material.

What goes in a qualitative codebook entry? The six-part format

A widely cited structure comes from MacQueen, McLellan, Kay and Milstein, “Codebook Development for Team-Based Qualitative Analysis” (Cultural Anthropology Methods, 1998). Each entry has six parts, summarized in this breakdown of the format:

Part What it holds
Code A brief tag coders apply while working through the data.
Brief definition One line stating what the code means.
Full definition A more thorough description of the concept the code covers.
When to use The features of a passage that should receive the code.
When not to use Similar-looking passages that belong under a different code, naming that code, so coders do not split the same kind of comment in different ways.
Example A real excerpt from the data that shows the code applied.

The “when not to use” field is what stops two coders from splitting the same comment in different ways.

Codebook for content analysis

A codebook for content analysis works as the coding manual: it lists each category, defines it, sets the unit of analysis (a word, sentence, paragraph or whole document), and gives decision rules for borderline cases. Because content analysis usually involves several coders, the codebook is tested on a sample before the full dataset is coded, and agreement between coders is then measured with a coefficient such as Cohen’s kappa for two coders or Krippendorff’s alpha for several. Low agreement on a category often points back to a vague definition or a missing exclusion rule, so revise the codebook and recode rather than averaging the disagreement away.

Exporting and sharing a codebook

You do not have to maintain the document by hand. MAXQDA, for example, exports a Word codebook listing the code structure and each code’s memo, where you write the definition, and it can add code numbering and a frequency column. For quantitative data, the Leibniz Psychology data guide recommends labeling every valid value and using distinct, standardized codes for different kinds of missing data rather than leaving blanks, since a blank cannot be told apart from a skipped entry.

Codebook vs. data dictionary

These two terms are often used interchangeably, which causes confusion. In practice, “data dictionary” is the broader, discipline-agnostic term for documentation that describes a dataset’s structure (fields, types, constraints), while “codebook” is the term most commonly used in the social and health sciences specifically for the version that includes value codes and, often, the substantive meaning of survey items. Every codebook is a kind of data dictionary; not every data dictionary is called a codebook. For a full breakdown of the fields each document typically contains, see data dictionary in research data management.

Codebook vs. DDI Codebook (the metadata standard)

“Codebook” is also the name of a specific machine-readable metadata standard: the DDI Codebook format from the Data Documentation Initiative. This is an XML specification for encoding exactly the kind of variable-level documentation described above so that it can be read by software and archived in repositories such as ICPSR. If you are looking for the XML/metadata standard rather than the general concept of “a document that defines my variables or codes,” that term is what you want — it formalizes the quantitative codebook described in this guide into a structured, interoperable format.

What a codebook documents beyond variables

The DDI Alliance, which maintains the Data Documentation Initiative standards, describes a codebook as documentation of a study that covers four layers: the study itself, the data files, the variables, and the categories (value codes) within variables. At variable level it says a codebook may include record layouts, variable names and labels, missing-value codes, frequency counts, notes and universe statements, and that this documentation supports replication by people who did not collect the data. A universe statement says which respondents or units a variable applies to, so a user can tell a skipped question from one that was never asked of that person.

The data table below compares which of these elements the DDI Alliance page and the Leibniz Psychology data guide each name. The two sources overlap on names, labels, missing codes and valid values, and each adds elements the other does not mention, so a complete codebook usually draws on both.

Naming variables and writing labels

The Leibniz Psychology data guide advises building variable names from letters, integers and underscores only, because the permitted length and case sensitivity differ between statistical programs. It recommends a prefix, root and suffix pattern, for example BDI_Q1_T1, where the prefix identifies the instrument, the root the item and the suffix the measurement occasion. The matching label spells the name out for humans: “Becks Depression Inventory, Question 1, Baseline”. Document the naming convention itself in a ReadMe file so that a new user can decode names they have not seen before; see what a README file is and file naming conventions for research data.

Missing-data codes in detail

A blank cell or a system-missing value cannot tell a reader why a value is absent. The Leibniz guide therefore recommends separate codes for each kind of missingness: missing by design, not applicable, not answered and unknown. Its examples are −77 for not applicable, −88 for unknown and −99 for missing by design. String variables can use NA or UK, and date variables a placeholder such as 01/01/1800. Every missing code needs its own value label, like any other value.

The same guide recommends declaring valid ranges so that impossible entries are caught. On a 5-point scale a recorded 6–99 range flags out-of-range data, and a heart rate above 220 is a prompt to check the entry. For how missing-data codes behave when exported from a survey tool, see missing-data codes in REDCap; for reasoning about why data are missing, see MCAR, MAR and MNAR.

Extended information to record

Beyond the core fields, the Leibniz guide lists extended information worth recording where it applies:

  • The item text or instruction, subject to third-party rights when the instrument is copyrighted.
  • The measurement occasion and the instrument or construct the variable belongs to.
  • The unit of measurement, the response unit and the unit of analysis.
  • Whether the variable is a filter variable that decides who sees later questions.
  • Imputation procedures, where values were filled in rather than observed.

The guide also recommends sending the draft codebook to a colleague from the intended audience: a reader who was not involved in data collection finds the gaps fastest.

Where codebook information comes from

According to the DDI Alliance, codebook information can come from a ReadMe file, from metadata embedded in SPSS, SAS or Stata data packages, or from extraction tools that read variable-level metadata out of a completed dataset. It names Nesstar Publisher, which writes DDI-Codebook 1.2 XML, Colectica, which works with DDI-Lifecycle 3.2, and Sledgehammer, and notes that a stylesheet can turn DDI XML into readable HTML as ICPSR does. These tools carry only metadata, never the data. Automatic extraction produces a first draft: the content still needs checking, because labels, missing codes and universe statements written into the original files may be incomplete.

How the DDI-Codebook 2.5 schema is organised

In the DDI-Codebook 2.5 XML schema, the root element codeBook contains up to five sections: docDscr (the document description, optional), stdyDscr (the study description, the only required section, repeatable), fileDscr (file descriptions, optional), dataDscr (data descriptions, which hold the variables, optional) and otherMat (other materials such as appendices, sampling or weighting documents, optional). The version attribute is fixed at “2.5”. This is the structure behind the term DDI Codebook.

Where qualitative codes come from

DeCuir-Gunby, Marshall and McCulloch, in “Developing and Using a Codebook for the Analysis of Interview Data: An Example from a Professional Development Research Project” (Field Methods 23(2):136–155, 2011, doi 10.1177/1525822X10388468), describe codes arising from three origins: theory-driven codes set in advance from a framework, data-driven codes that emerge from reading the data, and context-specific codes tied to the particular project. A team usually combines them, and the codebook is where each code’s origin, definition and boundaries are recorded. For worked analysis routes see thematic analysis explained.

Common mistakes

  • Writing the codebook after coding is finished. A codebook built retroactively tends to describe what one coder happened to do rather than a rule a second coder could follow. Draft definitions before or during the first pass, and revise as needed.
  • Vague code or variable definitions. “Positive experience” is not a usable code definition; “participant explicitly states satisfaction with wait time or staff responsiveness” is.
  • No missing-value convention. Treating blank, “not applicable,” and “refused” as the same thing loses information that often matters for analysis.
  • No version history. Codebooks change as datasets and coding schemes evolve; without dated versions, it becomes impossible to know which codebook applies to which wave of data.
  • No inclusion/exclusion criteria in qualitative codebooks. A code name and one-line definition are rarely enough to get two coders to agree; boundary cases need to be spelled out explicitly.

Frequently asked questions

What is a codebook in research?

A codebook is a document that defines the meaning of every variable (in quantitative research) or every code (in qualitative research) used in a study, so the data can be interpreted consistently and independently of the person who originally collected or coded it.

What is the difference between a codebook and a code book?

None — “codebook” and “code book” are the same concept, just written as one word or two. Both refer to the same type of research documentation.

Is a codebook the same as a data dictionary?

They overlap heavily. “Data dictionary” is the broader term for structural documentation of a dataset; “codebook” is the term most often used in social science and health research for the version that also documents value codes and item meaning. See the comparison above.

Do qualitative studies need a codebook?

Yes, if the analysis involves systematic coding of text (thematic analysis, content analysis, framework analysis, much of grounded theory). A codebook is what makes qualitative coding auditable and, when more than one coder is involved, comparable across coders.

What software is used to build a qualitative codebook?

Common choices include NVivo, ATLAS.ti, and MAXQDA, all of which let researchers define codes, apply them to text, and export the codebook as a standalone document. The codebook itself is a description of the coding scheme, not something that requires any particular software to exist.

How should missing values be coded?

Use a distinct, labelled code for each kind of missingness, such as −77 for not applicable, −88 for unknown and −99 for missing by design, rather than blank cells, and give every missing code a value label in the codebook (Leibniz Psychology data guide).

How do I name variables?

Use letters, integers and underscores only, in a prefix, root and suffix pattern such as BDI_Q1_T1, and explain the convention in a ReadMe file.

What is the difference between a codebook and DDI Codebook?

A codebook is any document that defines a study’s variables or codes. DDI Codebook is a specific XML metadata standard, now at schema version 2.5, for expressing that documentation in machine-readable form.

Can a codebook be generated automatically?

Partly. Tools can extract variable names, labels and value codes from SPSS, SAS or Stata files, but the DDI Alliance guidance treats this as metadata extraction only; a person still needs to check the content and add what the files do not contain, such as universe statements and notes.

Sources

Data: What each of three codebook sources says a codebook records

Which codebook elements the DDI Alliance 'Creating a DDI Codebook' page and the Leibniz Psychology data guide codebook page each name. Values are 'named' or 'not named'.

Period covered: 2026.

What each of three codebook sources says a codebook records
ElementDDI Alliance 'Creating a DDI Codebook'Leibniz Psychology codebook pageLeibniz recommendation or DDI wording
Variable namesnamednamedLetters, integers and underscores only; use prefix/root/suffix scheme such as BDI_Q1_T1 (Leibniz)
Variable labelsnamednamedShort description or full name, e.g. Becks Depression Inventory, Question 1, Baseline (Leibniz)
Missing value codesnamednamedSeparate codes per kind of missingness; no blanks or sysmis (Leibniz)
Valid values and value labelsnamed (as categories)namedList all valid codes and label every value including missing codes (Leibniz)
Variable typenot namednamedAt minimum numeric, string, date (Leibniz)
Record layoutsnamednot namedDDI Alliance: may include record layouts
Frequency countsnamednot namedDDI Alliance: may include frequency counts
Universe statementsnamednot namedDDI Alliance: universe statements
Notesnamednot namedDDI Alliance: notes
Item text or instructionnot namednamedInclude, subject to third-party rights (Leibniz)
Unit of measurementnot namednamedPart of extended information (Leibniz)
Imputation proceduresnot namednamedPart of extended information (Leibniz)

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about Codebook: What It Is, What Goes in One, and How to Build One

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →