Engineering / Field note
A Drupal configuration export does not move the content
Drupal configuration carries definitions such as content types, fields and Views. The records and files using those definitions need their own migration or editorial workflow, with separate acceptance evidence.
A Drupal configuration export can carry the definition of a content type, its fields and the View that lists it. The articles, records and uploaded files using that structure belong to a different part of the system. A successful configuration import therefore establishes the presence of definitions; the content still needs its own route into the destination. [1] [2]
This distinction is part of Drupal’s long-standing configuration model for Drupal 8 and later. The official configuration workflow page was updated in September 2023; this field note applies that documented separation to release acceptance and data ownership. [1]
A definition and a record are different deliverables
Drupal’s Configuration API guide distinguishes configuration, content, operational state, sessions and caches. Its examples put content types and taxonomy vocabularies among definitions, while individual content nodes and taxonomy terms are content. It offers the site-builder versus site-editor distinction as a useful guideline, with exceptions rather than an absolute rule. [2]
As a hypothetical example, imagine a museum adding a collection directory. The configuration describes an Object content type, fields for material and date, and a public listing. The actual object records, descriptions and photographs are content. Shipping the definitions can make the directory available to populate; it does not demonstrate that the collection’s records or images arrived.
That difference changes what a project owner should expect from a deployment report. In our view, “the configuration imported” and “the collection is ready for visitors” are separate claims. The first can be true while the second remains unfinished. A release conversation becomes clearer when each claim has its own owner and evidence.
By default, Drupal stores active configuration in its database and exports it as YAML. The workflow checks matching site UUIDs when synchronizing environments. Extension defaults in a module or theme’s config/install directory are read when that extension is installed; editing those files later does not automatically change active configuration. [1]
Our interpretation is that a repository can contain both the defaults used to create a site and the exported configuration describing an existing site. Their presence in the same release artifact does not make them interchangeable. A change intended for an established installation needs to be considered in the context of the configuration it is already running.
Content needs an explicit transfer process
Drupal’s Migrate API supplies a framework for moving data through source, process and destination stages. The source can be a database, file or web service. Processing transforms or skips a row, and the destination saves the result. The documentation also describes dependencies, such as migrating users before content that refers to them. [3]
The Migrate API’s map tables retain source identifiers, destination identifiers and row hashes. Those relationships support tracking changes and looking up migrated items from later migrations. This is a different responsibility from importing a definition of the fields those items will use. [3]
For the hypothetical museum, our acceptance question would concern the records that should be present, the relationships they retain and the media visitors can actually retrieve. Aggregate counts can help, but a matching count alone would not show that each object has the right image or description. The evidence should connect the source records with the intended published result.
This does not require treating every editorial change as a bulk migration. The important point is to name the route: a controlled import, a repeatable migration, or ordinary editing in the destination. Each has different implications for ongoing work, repeated execution and responsibility for corrections. Configuration synchronization does not choose that policy on the organization’s behalf.
The release boundary also shapes recovery
Drupal’s information model treats state and cache separately from configuration. State can describe runtime conditions, while a cache stores derived information rather than canonical records. Our reading is that a configuration export should be described by the information it actually contains, rather than presented as a complete snapshot of everything the site needs. [2]
That separation matters when planning recovery. Reverting code or importing an earlier configuration does not, by itself, describe what should happen to content created since the change. In our assessment, the recovery decision needs to account for the accepted definitions, current editorial work and any imported records affected by the release.
The practical outcome is a release record that distinguishes structure from the material it organizes. The configuration can be reviewed as one artifact, and content readiness can be established through its own evidence. That gives a site owner a more useful completion statement than a green import result attached to an empty directory.
Sources + further reading
Source dates describe the original material. Publication above is the date this Zyel article went live.
- Managing your site’s configurationDrupal Documentation · Checked Nov 14, 2026
- Configuration and other types of informationDrupal Configuration API documentation · Checked Nov 14, 2026
- Migrate API overviewDrupal Documentation · Checked Nov 14, 2026
Reader discussion
What would you ask next?
Questions, useful corrections and thoughtful disagreement are welcome. Comments are reviewed before they appear.
No reader comments yet.