Map Data Contracts

Context

This came from integrating multiple map features with different backend services. Each service had its own shape for entities, geometries, and metadata. The frontend map layer was constantly adapting to backend changes.

What I started noticing

Map components were coupled to specific API responses. A change in the backend schema forced updates across the frontend. Validation and normalisation were scattered. It was unclear what “a map entity” looked like from the UI’s perspective.

The approach that worked better

Define frontend-facing data contracts for entities, geometries, and metadata. Backend responses are mapped to these contracts at the boundary (e.g. in API clients or hooks). The map layer only knows the contract; it doesn’t care which service the data came from.

Why this mattered

• Maintainability: Backend changes are absorbed in one place (the adapter).
• Scalability: New data sources can be added by implementing the same contract.
• Clarity: The map code expresses intent in terms of domain types, not API shapes.
• Team productivity: Backend and frontend teams can evolve independently with a clear contract.

Trade-offs

Contracts can drift from backend reality if not maintained. Mapping adds a small performance and code cost. For very simple, single-source integrations, a direct coupling might be acceptable.

What I would keep doing

Keep contracts minimal and stable. Version them if they must change. Prefer optional fields and extensibility so new properties don’t break existing consumers. Document the contract and who owns it.

Related Notes

• Map Core Architecture
• MobX Architecture Patterns