Backend Development - Typed Data API

By saroj 15 February, 2026 Difficulty: Intermediate

In the previous topic, we worked with the Entity API and performed CRUD operations. Now we go one layer deeper into Drupal’s internal architecture: the Typed Data API.

Typed Data is the system that gives structure and meaning to values stored in entities and fields. It powers:

  • Field validation
  • Data constraints
  • REST and serialization
  • Form validation
  • Entity property access

If Entity API is how you interact with data, Typed Data API is how Drupal understands what that data is.

This topic continues the learning-by-building approach using the same weeklydrupal_demo module and the custom rating field type created earlier.

By the end of this article, you will understand:

  • What typed data is
  • How fields use typed data definitions
  • How property definitions work
  • How constraints and validation integrate
  • Why typed data matters for backend architecture

1. What Is Typed Data

Typed Data is Drupal’s system for describing data in a structured way.

It answers questions like:

  • Is this value an integer or string?
  • Is it required?
  • Does it have constraints?
  • Can it be empty?

In simple terms:

Typed Data defines the type and rules of a value.

2. Where Typed Data Is Used

Typed Data is used in:

  • Field types
  • Entity properties
  • Configuration objects
  • REST responses
  • Validation system

Every field value in Drupal is a typed data object.

3. Typed Data in Our Custom Field Type

Earlier, we defined this in RatingItem:

public static function propertyDefinitions(FieldStorageDefinitionInterface $field_definition) {
  $properties['value'] = DataDefinition::create('integer')
    ->setLabel(t('Rating value'));

  return $properties;
}

What this means

  • value is a property of the field
  • It is defined as an integer
  • Drupal now knows how to validate and store it

This is Typed Data in action.

4. DataDefinition

DataDefinition::create('integer') tells Drupal:

  • The value must be an integer
  • It can apply integer validation
  • It integrates with constraints

Other common types:

  • string
  • boolean
  • float
  • entity_reference
  • map

Typed Data ensures consistent behavior across the system.

5. Accessing Typed Data Programmatically

When you load an entity:

$node = \Drupal::entityTypeManager()->getStorage('node')->load($nid);

Accessing a field value:

$value = $node->get('field_rating')->value;

Behind the scenes:

  • field_rating is a FieldItemList
  • Each item contains typed data
  • value is a typed property

6. FieldItemList and FieldItem

Understanding layers:

  • Entity
  • FieldItemList (collection of values)
  • FieldItem (single value)
  • Typed Data property

Example:

$field = $node->get('field_rating');
$item = $field->first();
$value = $item->value;

Each level is structured and typed.

7. Validation and Constraints

Typed Data integrates with the Validation API.

Example: Add a range constraint to rating.

$properties['value'] = DataDefinition::create('integer')
  ->setLabel(t('Rating value'))
  ->addConstraint('Range', ['min' => 1, 'max' => 5]);

Now Drupal will automatically validate:

  • Values below 1
  • Values above 5

No manual validation required in the widget.

8. Why Typed Data Matters for REST and APIs

When Drupal exposes data via REST:

  • Typed Data definitions determine serialization
  • Data types are respected
  • Validation rules are enforced

Typed Data ensures backend consistency.

9. Creating Custom Typed Data Types

Advanced use case:

You can create custom typed data classes when:

  • Complex nested structures are required
  • Specialized validation logic is needed
  • Custom data handling is required

Most backend developers use Typed Data through field types rather than creating standalone typed data classes.

10. Common Mistakes to Avoid

  • Ignoring property definitions in field types
  • Skipping constraints when validation is required
  • Treating field values as raw arrays
  • Writing custom validation instead of using constraints

Typed Data exists to centralize validation and structure.

11. Learning by Building: weeklydrupal_demo

We can now improve our rating field by:

  • Adding range constraints
  • Making the field required
  • Testing validation through forms
  • Ensuring API responses respect type

This connects:

  • Field Types
  • Widgets
  • Formatters
  • Entity CRUD
  • Validation system

12. Why Typed Data API Is Important

Understanding Typed Data helps you:

  • Design better field types
  • Write safer backend logic
  • Build clean API integrations
  • Avoid duplicate validation logic

Typed Data is one of Drupal’s most important internal architecture layers.