Drupal migration mapping validator

#devlog #agents #ai

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

I shipped a Drupal migrate mapping validator utility that catches broken mappings before they land in prod.

Why I Built It
Migration debugging is a time sink when a single typo in a mapping silently drops fields. I wanted a fast, deterministic way to validate mappings against source schemas and destination field definitions so I could fail early instead of squinting at logs later.

The Solution
I built a validator that loads migration YAML, resolves plugin chains, then checks each mapping against source keys and destination field types. It surfaces conflicts with clear, line-level errors so I can fix the right mapping in minutes.

graph TD;
  A[Migration YAML] --> B[Parse + Normalize];
  B --> C[Resolve Plugins];
  C --> D[Validate Source Keys];
  C --> E[Validate Dest Fields];
  D --> F[Report Issues];
  E --> F[Report Issues];

```bash
drupal-migrate-validate --migration user_profiles --strict
```

```yaml
validator:
  strict: true
  allow_missing_sources: false
  field_type_checks: true
```

Click to view raw logs
[validate] migration=user_profiles
[ok] source keys: 18
[error] mapping: field_bio -> source:bio_text (missing)
[error] field type mismatch: field_age expects integer, got string

:::tip
Failing fast on mapping errors is the cheapest performance optimization you can buy.
:::

The Code
View Code

What I Learned

Pantheon’s Site Dashboard now exposes top IPs, user agents, and paths, which makes anomaly triage much faster for ops reviews.
A Drupal CSS aggregation bug can surface as missing styles only in production, so I now add an aggregation-on check to my smoke tests.
The Drupal community is debating algorithmic bias in tooling recommendations, and it’s a useful reminder to evaluate “default” platform choices critically.

:::warning
Aggregation issues can hide until cache layers are warm. Test with aggregation enabled.
:::