DDI Codebook

DDI Codebook (DDI-C) is an XML-based metadata specification, maintained by the Data Documentation Initiative (DDI) Alliance, used to describe the content, structure, meaning, provenance, and access conditions of a single dataset — most commonly survey and other observational data from the social, behavioral, economic, and health sciences. A document is a valid instance of DDI Codebook when its root element is codeBook and it carries the standard’s core sections: a study description (title, authorship, abstract, methodology, sampling), a file description for the physical data file(s), and a data description that documents each variable individually — its name, label, question text, value labels, universe, and any derivation notes.

Where DDI-C fits in the DDI family

DDI Codebook (sometimes written DDI 2.x, since it is versioned 1.0 through 2.5/2.6) is the older, simpler branch of the DDI specification, built around describing one dataset at a time. The DDI Alliance also maintains DDI Lifecycle (DDI 3.x), a more complex model designed to track a dataset across its full lifecycle — multiple waves of a longitudinal survey, question banks reused across studies, and relationships between related data products. DDI-C remains widely used precisely because it is simpler to produce and consume for a single, self-contained dataset, and many social science data archives still accept or require it as a deposit format. It is a specific example of the broader concept covered in metadata schema: a discipline-specific documentation format, in the same family as (but distinct from) generic repository schemas like DataCite’s, and from purpose-built schemas for other domains such as Ecological Metadata Language for ecology data.

Worked examples

• A university social science data archive receiving a deposited survey dataset asks the depositing researcher for a DDI Codebook XML file alongside the raw data, so that variable-level documentation (question wording, response codes, missing-value conventions) travels with the dataset rather than living only in a separate PDF codebook.
• A cross-national survey program (for example, a multi-country attitudes survey) publishes each national dataset with a DDI-C record so that secondary users can programmatically compare variable definitions and value labels across countries before merging files.
• A repository built on tools such as Nesstar, Colectica, or DDI-compliant modules of Dataverse generates or ingests DDI Codebook XML automatically as part of its variable-browsing and dataset-citation interface.

Counter-example

A plain-text README describing a dataset’s columns in prose, with no machine-readable element structure, is not DDI Codebook — it may serve a similar documentation purpose, but it lacks the standardized, parseable XML elements (codeBook, stdyDscr, var) that let software validate, index, and exchange the description consistently. Likewise, a schema.org/Dataset JSON-LD block embedded on a webpage is not DDI-C: it is designed for general web discoverability by search engines, not for the fine-grained, variable-level documentation DDI-C provides.

Choosing DDI Codebook

Researchers and data managers deciding whether DDI-C is the right documentation format for a dataset — versus a generic repository schema, a discipline-specific alternative, or DDI Lifecycle — should weigh the trade-offs covered in How to Choose a Metadata Schema for a Dataset. In general, DDI-C is the stronger fit when the data is survey- or questionnaire-based, single-dataset in scope, and destined for a social science archive that already expects it.