Drupal: Field Types and Entity References

A field is not one object but a small stack of configuration and plugins. Knowing which layer owns which setting explains most of the questions editors and site builders ask ("why can I not change the number of values?", "why does my setting apply to every content type?").

The following diagram shows how these layers relate for the Meridian Museum event content type.

For a configurable field on a node the values live in a dedicated table (node__field_event_dates, plus node_revision__field_event_dates for revisions), one column per property (field_event_dates_value, field_event_dates_end_value). A base field, in contrast, is declared in code in baseFieldDefinitions() of the entity class and stored in the entity’s own table. Base fields cannot be created or deleted from the UI; their widgets and formatters can still be configured. Entity queries and Views hide this difference.

Cardinality deserves a note because it is a common pitfall: raising it from "1" to "unlimited" is allowed at any time, but lowering it, or changing a storage setting such as target_type or the list of allowed values' keys, is refused once data exists. Plan the storage up front, or migrate the data.

A UI note for people following older tutorials: since Drupal 10.2 the Field UI first asks for a group of types (for example "Reference", "Text", "Number", "Date and time") and then for the concrete type. The names of the plugin IDs have not changed, only the wizard in front of them. The Drupal User Guide chapter on content structure (6.x) follows the newer flow.

Source: Drupal User Guide: Adding Basic Fields to a Content Type

Drush 13 and 14 include field:create, so a field can be created without clicking, which is handy in a deployment script, a recipe’s preparation step or a local rebuild.

Source: Drush: field:create

Fields created this way are ordinary configuration. The sensible workflow is the one in Configuration management: create on a development site, export, review the YAML diff and import on the other environments. Reusing an existing storage on another bundle is possible in the UI ("Re-use an existing field") and with the --existing option.

The table lists the field types that a site builder meets most often. The module in the second column must be enabled for the type to appear.

Source: Drupal User Guide: Adding Basic Fields to a Content Type

Two cross-cutting rules apply to all of them. First, plain-text types store text as entered and rely on output escaping, while formatted types store the text together with the text format that decides which markup survives filtering (see Text formats and CKEditor 5). Second, the storage layer does not validate business rules: required, minimum, maximum and similar settings are enforced by field constraints in the form and the entity API, not by the database.

Plain text (string, string_long) has a maximum length (255 characters by default for string) and a single-line or multi-line widget. Use it for data that is never shown as markup: the Meridian accession number (2026.14.3), a catalogue code, a title. Formatted text (text, text_long, text_with_summary) additionally stores a text format. The "summary" variant is what the body field of a node uses; the summary can be shown in teasers.

Pitfalls:

List fields (list_string, list_integer, list_float, with the Options module) store one of a fixed set of keys and show a label. The allowed values are part of the storage because they define which keys are legal. In the UI they are entered as key|Label lines; in configuration they are a sequence under settings.allowed_values.

Source: Drupal APIs: Configuration schema and metadata

Use stable, machine-readable keys (roman), never labels, because the key is what is stored, exported and used in queries. Removing a key that is already in use is blocked by the form; renaming it requires an update path that rewrites the stored values. When the options must come from code (for example the open galleries), set allowed_values_function to a function or a static method that returns the array. A list that editors need to maintain belongs in a taxonomy and an entity reference, not here (see Taxonomy).

The widgets are a select list, radio buttons or check boxes (the latter two chosen automatically for single or multiple values in the form display), and the formatters show the label or the key.

Numbers come in three storage types. integer has a size (tiny to big), optional minimum, maximum, prefix and suffix. decimal stores an exact value with a declared precision and scale and is the type for money (the ticket price of a workshop). float is a binary floating-point number: use it for measurements, never for currency, because it cannot represent most decimals exactly.

A boolean field stores 0 or 1 and has configurable on and off labels. Its widget is a single check box or a pair of radio buttons. The Meridian on_display property is a boolean. Two common mistakes follow from how it is stored. First, "unchecked" is a stored 0, not a missing value, so a Views filter "is not empty" does not mean what an editor thinks; filter on the value. Second, labels that look like questions ("Is this on display?") confuse screen-reader users in the "off" state: use a label that works in both ("On display") and describe the meaning in the help text.

Core has three families, and choosing the wrong one is the most frequent date mistake.

Datetime Range is a core module, but it is not enabled by the Standard profile in every version, so a recipe or installation that needs the type should list datetime_range explicitly. In the Meridian site the event dates field looks like this in configuration.

Source: Drupal APIs: Configuration schema and metadata

Pitfalls to know:

For the code side of a range query see Database API and entity queries.

Link (link, Link module) stores a uri, an optional title and an options array. The URI can be an internal path (internal:/visit), an entity (entity:node/12), a route (route:<front>) or an external address. Storage settings: none; instance settings choose whether the title is optional, required or disabled and whether external links, internal links or both are allowed. The Meridian ticket_link of an event is a link field with an external-only restriction. Two practical points: the formatter can add rel="nofollow" and target through formatter settings, and the field validates the URI scheme, so javascript: URIs are rejected, which is the security-relevant behaviour you want to preserve in any custom widget.

Email (email) stores one address and validates its syntax; the formatter can render a mailto: link. Showing addresses as links invites harvesting by spam bots, so the museum publishes a contact form instead (see Forms for visitors: Contact and Webform).

Telephone (telephone, Telephone module) stores a string and a tel: link formatter, with no format validation (a phone number differs by country). The Telephone module is being removed from Drupal core in Drupal 12.0.0 and continues as a contributed project: the deprecation change record names Drupal 11.5.0 as the release that deprecated it, while the removal planning for 11.4 also appears in the tracker, so check the change record of the release you run. Existing fields keep working as long as the contrib module is installed; the safe sequence before upgrading is to install the contrib version while still on Drupal 11 and not to uninstall the core module first (see Removed core modules and replacements). An alternative is a plain string field plus a validation constraint, or the Telephone Validation contrib module that checks numbers per country.

Source: Change record: Telephone module deprecated

File (file, File module) stores a reference to a managed file entity in target_id plus a display flag (whether the file is shown) and a description. Image (image, Image module) adds alt, title, width and height. Both are entity references in disguise: the value is the id of a file entity stored in the file_managed table, with usage tracked in file_usage. That is why deleting a node does not immediately delete its files: they become temporary and are removed by cron after the configured maximum age.

Field settings that matter:

Source: Drupal User Guide: Adding Basic Fields to a Content Type

For editorial content, prefer a media reference over a bare image field. A media entity gives you a reusable library, a reusable alt text, per-type fields (a credit line, a licence) and the Media Library widget. A bare image field is simpler and perfectly adequate for a one-off such as a user picture. The responsive output of both goes through image styles (see Media and the Media Library and Display modes and image styles).

The comment field type is unusual: it does not store a value that the editor types. It stores the comment status of an entity (open, closed or hidden) and denormalised statistics (last comment id, timestamp and author, comment count), and it points at a comment type that defines the fields of the comments themselves. The Comment module therefore needs two steps in the UI: create a comment type (Structure > Comment types), then add a field of type "Comments" to the content type. Field settings control the default mode (threaded or flat), the number of comments per page, whether anonymous visitors may leave contact information, preview and the form location.

Because comment fields are normal fields, one entity can have several comment fields, and comments can be attached to any content entity (including a custom entity such as collection_object) by adding a comment field to its bundle. Moderating spam is part of operating comments: keep anonymous commenting off, require approval ("Comments require approval" via permissions), and use a CAPTCHA or an anti-spam service if the museum ever opens comments to the public. Comments are excluded from search and from the default JSON:API fields unless exposed deliberately. For most editorial sites a "contact the curator" form or a discussion on a social platform is lower maintenance than a comment system.

An entity reference stores the id of another entity (target_id) and, in the storage settings, the type of entity it may point to (target_type: node, taxonomy_term, user, media, file, collection_object and so on). It is the mechanism behind every relationship in Drupal: an exhibition showing objects, an event in a gallery, an object made of a material term, a news item written by a user. Core’s entity_reference module is always on; taxonomy term fields, media fields, file and image fields and the author of a node are all built on the same idea.

The decisions to take when creating one are:

The field instance configuration of the exhibition-to-object reference looks like this.

Source: Drupal User Guide: Adding a Reference Field

The matching storage file declares settings.target_type: collection_object. Note the dependency on both the storage and the bundle: configuration dependencies are what make a config import fail early, not at runtime, when something is missing.

The "Reference method" on the field instance is a choice among selection plugins (plugin type EntityReferenceSelection, discovered in Plugin/EntityReferenceSelection). A selection plugin does two things: it returns the entities that can be selected for a given search string, and it validates that a submitted value is one of them. The latter makes selection a real server-side check, not merely a UI filter.

Source: API: EntityReferenceSelection attribute

The handler and its settings live under settings.handler and settings.handler_settings of the field instance, as in the configuration above. For a nodes' target the default handler restricts to selected content types: leaving target_bundles empty means "any bundle", which is often too wide, so pick them explicitly.

The selection API is small. Plugins implement SelectionInterface, usually by extending DefaultSelection: getReferenceableEntities($match, $match_operator, $limit) returns ids grouped by bundle, countReferenceableEntities() counts them, validateReferenceableEntities(array $ids) filters submitted ids and createNewEntity() and validateReferenceableNewEntities() support auto-creation. Modules can also adjust a handler without writing one with hook_entity_reference_selection_alter() and the query alter hooks entity_reference_selection.

An entity reference is stored on one side only. The exhibition knows its objects; the object does not store the exhibitions that show it. Drupal core has no "reverse reference" field type, so a back-link is built when it is needed:

The pitfalls are performance and cache invalidation. A reverse View on a large site is a join over the field table; give the referenced field an index in the View or restrict by bundle. Cache tags on the page that shows the reverse list must include the list tag of the referenced entities so that a new exhibition appears (Views adds the node_list tags automatically). The query itself is expressed like this.

Source: Drupal APIs: Working with the Entity API

The class is registered as a service in meridian_collection.services.yml with the argument @entity_type.manager; see Services and dependency injection.

Configurable fields are for site builders; a custom entity type declares its own fields as base fields. The same field type, widget and formatter plugin IDs are used, so everything on this page applies. The excerpt below is the part of the collection_object entity that defines the data fields of the museum collection (the rest of the class is in Custom entity types).

Source: Drupal APIs: Defining and using content entity field definitions

Changing a base field definition after the entity type is installed requires an update path (an entity definition update through the Update API, see Update API and post-updates), because the schema and the stored definition must stay in step. Older books such as Drupal 10 Development Cookbook (2023) show this code with plugin annotations in a @ContentEntityType doc comment; since Drupal 10.2 the same plugins are declared with PHP attributes, and annotations are on a deprecation path.

Core field types model attributes and relationships. Contributed projects add richer building blocks. They are useful, but each is a long-term commitment, so this section describes what they do and what they cost.

Source: Paragraphs project page

Alternatives are often better than reflexively adding Paragraphs. A structured exhibition page with a hero, a text section and a gallery strip can be built with core fields plus Layout Builder (see Layout Builder), or with Canvas, which renders Single Directory Components and code components for editors (see Canvas visual page building). The Drupal CMS 2.0 documentation does not describe an automatic migration from Paragraphs or Layout Builder to Canvas, so a site that adopts Canvas should plan to move that content itself. Whatever you choose, treat contributed field types as upgrade risk: before a major upgrade check each project for the next core version (see Preparing for Drupal 12).

A related warning from the core removals: modules that older tutorials rely on (Statistics, Book, Forum, Tour and others) were removed in earlier majors, and the Telephone module follows in Drupal 12. The correct preparation is to install the contrib replacement first and to never uninstall the core module before the upgrade.