Content Types and Fields

Two families of entities exist, and the distinction determines where things are stored.

A content type is itself a config entity. The exhibition bundle you create in the UI is exported as node.type.exhibition, and every field you add to it creates further config entities. The content created from it (exhibition pages) is stored as node content entities. This split between the model (configuration) and the data (content) is the reason that moving a model forward is a configuration deployment, while moving content needs migrations or a content synchronisation tool.

The figure shows the five layers described in the rest of the page. An entity type owns base fields and has bundles. Each bundle gets field instances; every instance points to a field storage that is shared by all bundles of the same entity type that use the same field name. Each bundle also has a form display and a view display that decide the widget and the formatter of every instance.

Go to Manage > Structure > Content types (/admin/structure/types) and choose Add content type. The form has these parts.

Click Save and manage fields. Drupal now has a bundle with no configurable fields: every node still has the base fields title, status, uid, created, changed, promote and sticky (plus the revision metadata fields), which is why the Create form is not empty even before you add a field.

Repeat for event, with the description "A single dated event at the museum, such as a talk or a workshop", the title label "Event name" and Create new revision enabled.

Once saved, the type exists as one configuration object. This is what drush config:export writes:

Source: User Guide: 6.1. Adding a Content Type

The keys map one to one onto the form: type is the machine name, name the label, new_revision the revision default, preview_mode is 0 (disabled), 1 (optional) or 2 (required), and display_submitted the author line. The default published and promoted state is not here: it is stored in a base_field_override file (see Base fields versus configurable fields).

Deleting a content type is allowed only while no content of that type exists; the User Guide’s section 6.2, "Deleting a Content Type", describes the screen. Deleting a type also deletes its field instances and display configuration, and purges the field storages that no other bundle uses (see What happens when a field is deleted).

This distinction is the most important idea of the Field system, and it is the one the UI hides best.

The practical effect is that one storage can serve several bundles. If you create field_dates on exhibition and later open Manage fields of event, you can Re-use an existing field and pick field_dates from the list: Drupal creates only a new field instance (field.field.node.event.field_dates), not a second storage and not a second table. The two bundles then share the table node__field_dates and the same cardinality, but each keeps its own label, help text, default value and required flag. The sharing has two consequences you should plan for:

Source: Drush: config:get

The machine name is chosen once. The UI prefixes it with field_ (the prefix is not required by the API, but is a convention of the UI and of every contrib module; configurable fields created by code can have any name that is not reserved). A machine name is limited to 32 characters including the prefix, so the name part has at most 25 characters. The name becomes the database table suffix (node__field_dates), the column prefix (field_dates_value), the name of the PHP property ($node->field_dates), the key in Twig (content.field_dates) and the key in JSON:API attributes. Plan names such as field_dates rather than field_exhibition_run_dates_2026: the name cannot change and a very long name makes the generated table names exceed the database identifier limit, in which case Drupal shortens them with a hash.

A field type defines what is stored and its columns. Drupal core ships many types, grouped by the module that provides them.

The full list, with the widgets and formatters each type offers, and the way to write your own, are in Field types and entity references and Field type, widget and formatter plugins. Modules the Standard profile no longer enables can remove types from the list: the Comment type is available only with the Comment module, Telephone only with Telephone (which Drupal 12 moves to contrib; see Preparing for Drupal 12).

Allowed number of values is a storage setting and is stored as cardinality: a positive integer, or -1, the value of the constant FieldStorageDefinitionInterface::CARDINALITY_UNLIMITED, for unlimited. In the UI you choose Limited and a number, or Unlimited. Cardinality matters in three ways.

You can raise the cardinality at any time. Lowering it on a field that already holds more values than the new limit leaves the surplus values in the table but no longer editable or validated, so reduce it only after checking the data with a query. Changing between "limited to 1" and "unlimited" is therefore safe in one direction (more values) and risky in the other. Be careful with 1 versus -1 in the JSON:API and Twig output as well: a single-value reference serialises as an object, a multi-value one as an array, so changing it later also changes API consumers.

These are instance settings, defined per bundle and stored in field.field.*.

The exhibition instance of the date field therefore looks as follows.

Source: API: FieldConfig class

and the shared storage it depends on:

Source: API: FieldStorageConfig class

Read the two files side by side with the Field UI. The config: dependencies of the instance name the storage and the bundle: exporting and importing a configuration set therefore creates the bundle and storage first, and deleting the storage removes every instance. The storage’s settings (here datetime_type: date, date without a time of day) are the type-specific storage settings; the instance’s own settings (empty here) are type-specific instance settings. For entity_reference the target type (target_type: taxonomy_term) is a storage setting and the allowed target bundles and their sort order (handler: 'default:taxonomy_term', handler_settings.target_bundles) are instance settings.

The keys locked, persist_with_no_fields and custom_storage are rarely used: locked forbids deleting the field in the UI (modules set it for fields they depend on), persist_with_no_fields keeps the storage when the last instance is removed, and custom_storage tells Drupal that a module stores the values itself, so no table is created.

Once an entity has data in a field, Drupal blocks storage changes that could lose or corrupt it. The UI then shows the storage settings as read-only with the message that "there is data for this field in the database". The type, the entity type and the machine name are always immutable. For example, the maximum length of a plain text field can be increased but not lowered, the target type of an entity reference cannot be changed, and an allowed-values list can have values added but not removed while content uses them. The safe path for a real change is usually to create a new field, migrate the data with an update hook or a migration, switch displays and queries and delete the old field. See Update API and post updates for the hook that performs the data move.

A link field illustrates that instance settings carry most of the editorial behaviour:

Source: User Guide: 6.3. Adding Basic Fields to a Content Type

In the link instance link_type: 16 means external links only (LinkItemInterface::LINK_EXTERNAL; 1 is internal only and 17 is both) and title: 0 disables the link text. The UI hides these numbers behind radio buttons, but you will meet them in the exported YAML.

The default form is core.entity_form_display.node.exhibition.default. Each entity type can have additional form modes (core.entity_form_mode.node.<name>), enabled per bundle under Custom display settings at the bottom of the Manage form display page; core defines a register form mode for users, so that the registration form can show fewer fields than the account edit form. The User Guide notes that this is rarely used for content. A form mode is a separate entity_form_display config entity per bundle and mode, for example core.entity_form_display.user.user.register.

Source: User Guide: 6.8. Concept: Forms and Widgets

Notice that base fields (title, status, path) are configured in the same file as configurable fields, and that anything not listed under content and not under hidden is simply not part of the form. Notice also that a field that exists but has no entry in this file does not appear on the form: this is why a field added by a recipe or an import can seem to "disappear" until a form display entry is added.

A custom content entity declares its own base fields, which is the usual way to store a fixed, central set of values. The collection_object entity of Meridian Museum defines accession_number that way (the full entity is built in Custom entity types):

Source: Entity API: FieldTypes, FieldWidgets and FieldFormatters

The calls setDisplayOptions() give the default widget and formatter that the entity ships with, and setDisplayConfigurable() lets a site builder still change them in the Field UI: without it the display of a base field is fixed in code. Cardinality is set with ->setCardinality(-1) (or the constant). Constraints such as UniqueField are added with addConstraint(). After adding or changing a base field definition in code you must apply the schema change through an update (hook_update_N() using EntityDefinitionUpdateManager or a post update); on the Status report a pending change appears as "Mismatched entity and/or field definitions", an error that older books also describe with the Drush entity:updates command, removed in Drush 9. Do not run a schema change on a live site without a database backup; see Update API and post updates.

A module can add a field to a bundle, without creating configuration, with hook_entity_bundle_field_info(). Since Drupal 11.1 hooks are implemented as attribute methods on a class in src/Hook (older Drupal 10 modules and books write a procedural function in the .module file), as shown here for the Meridian module:

Source: Change record: Support for object oriented hook implementations

Fields defined this way are code-defined, appear in Manage display but are not exported as field.storage.*, and are suited to computed values. For a stored value, create a configurable field instead: it is simpler, exportable and translatable. Hooks and the OOP hook system are covered in Hooks and OOP hooks.

A dedicated table per configurable field is what lets a site builder add a field without altering a shared table: adding field_capacity creates node__field_capacity (and the revision table) and nothing else. It also makes multi-value fields natural and lets Views join only the fields it needs. The cost is more joins: a node with twenty fields needs a join per field, which is one of the reasons the page cache, the render cache and Views caching matter (see Performance and caching) and why a content model with several hundred fields per bundle is an anti-pattern. Entities with custom_storage: true fields, or entity types using a non-SQL storage, behave differently, and Drupal itself can use a shared table layout for base fields only. Wide content models are better split across several entities with references than put in one very wide node.

Both translation and revision support are properties of the entity type (the node declares both) and of each field storage. For translatable fields, one row per language is stored; for non-translatable fields, the single value is shared by every translation. Revisions copy field values into the *_revision tables each time a new revision is saved; this is why the Create new revision default matters for the table size, and why moderation workflows (see Content moderation, workflows and revisions) create many rows.

An update hook or a recipe-like script creates fields with the same config entities the UI uses. Add the storage first, then the instance, then the display entries:

Source: Entity API: FieldTypes, FieldWidgets and FieldFormatters

Guard with loadByName() so that the script can run again, and keep in mind that the configuration the script creates must also be exported, or the next config:import will delete the field (it is not in the sync directory). In a recipe, the same model is expressed as exported YAML files in the recipe’s config/ directory plus a recipe.yml that lists its module dependencies; the meridian_events recipe ships exactly the event files shown on this page, and a recipe cannot update a field that already exists with different settings, so it is meant for fresh sites.

The entity API hides the table layout. Field items are objects with properties; the "main property" gives the common value.

Source: Entity API: Working with the Entity API

An entity query searches by field and bundle, and must state whether to check access.

Source: Entity API: Working with the Entity API

The \Drupal:: static call is acceptable in a script, but in a service or controller inject EntityTypeManagerInterface, as explained in Services and dependency injection. A query without accessCheck() throws an exception in current Drupal versions; the older books that omit it describe behaviour of Drupal 8 and 9, where it only emitted a deprecation. In Drupal 12 query objects are also no longer serialisable, so do not store them in the cache or in a queue item.