# Domain Sync Protocols for Spatial Data

Deterministic state propagation across autonomous spatial domains within the Federated Ownership & Routing Architecture.

Domain synchronization operates as the control plane that propagates spatial state — feature edits, tile invalidations, schema patches — across isolated domain boundaries without coupling their internals. For data architects, platform engineers, and GIS data stewards, production-ready sync protocols demand strict architectural separation, explicit contract enforcement, and measurable service-level agreements (SLAs). This guide defines the procedural implementation of spatial sync workflows so that cross-domain dependencies stay decoupled, auditable, and resilient under enterprise routing loads. It sits one layer below the Schema Contracts for Vector/Tile Data that govern payload shape, and it feeds the Cross-Domain Routing Strategies that decide where validated changes travel.

Figure — Spatial changes propagate through validation and a partitioned broker with exactly-once, conflict-resolved delivery.

# Architectural Boundaries & Design Rationale

The foundation of spatial domain sync is enforcing strict boundary isolation while preserving a unified routing topology. Each domain is an autonomous unit with its own spatial data products, compute resources, and governance policies — boundaries first established through Spatial Domain Boundary Design. Cross-domain synchronization is mediated through a control plane that routes state changes without exposing underlying infrastructure or raw datasets, treating domain edges as immutable security perimeters rather than convenience seams.

This separation exists to prevent three concrete failure modes. First, topology drift: when a consumer applies the same edit twice, ring orientations and shared edges silently diverge from the source of truth. Second, schema-bleed cascades: an un-versioned attribute change in one domain corrupts every downstream tile cache that assumed the old contract. Third, blast-radius coupling: a synchronous fan-out call lets one slow domain stall the whole mesh. The protocol answers each with, respectively, idempotent keys, contract gates upstream of the broker, and an asynchronous partitioned transport.

Implementation begins by provisioning domain-scoped message brokers and configuring topic partitions that map to specific spatial extents — UTM zones such as EPSG:32633, administrative boundaries, or tile-matrix grids. Platform engineers enforce namespace isolation at the network layer using VPC peering restrictions, private service endpoints, and domain-specific DNS resolution. All sync traffic traverses a dedicated control channel that logs metadata-only payloads during the initial handshake, ensuring bulk spatial transfers never bypass domain routing policies. Where a change requires enrichment that may fail, the protocol defers to the Fallback Chains for Geocoding Services pattern, and where the transformation is heavy it offloads to Async Execution for Heavy Spatial Queries rather than blocking the sync path.

# Example: Domain-scoped Kafka topic partitioning by spatial grid
kafka:
  topics:
    - name: spatial.sync.vector
      partitions: 360
      replication.factor: 3
      config:
        retention.ms: 604800000
        cleanup.policy: "compact"
        min.insync.replicas: 2

Note: partitioner is a producer-side configuration, not a topic-level property. To route messages to partitions by spatial grid, implement a custom org.apache.kafka.clients.producer.Partitioner on the producer and configure it via the producer’s partitioner.class property rather than in the topic definition.

# Specification & Contract Reference

Every sync message carries a metadata envelope that the control plane evaluates before the payload reaches a partition. The envelope is contract-bound: a message missing a mandatory header, or declaring a coordinate reference system outside the domain’s allow-list, is rejected at ingress with 422 and never enters the broker. Spatial precision is pinned to the declared CRS — geographic payloads in EPSG:4326 are stored at 7 decimal places (~11 mm), while web-mercator EPSG:3857 and projected UTM (EPSG:32633) payloads are stored in metres to 3 decimal places.

Schema validation at the ingestion boundary is non-negotiable. Domain sync protocols enforce the versioned contracts defined by Schema Contracts for Vector/Tile Data, which fix the acceptable geometries, coordinate reference systems, attribute types, and topology rules before a payload is allowed onto the wire. Validation logic must include CRS normalization gates that reject non-conforming projections, topology checks that flag self-intersecting polygons and invalid ring orientations, tile-boundary alignment checks that snap MVT coordinates to grid thresholds, and backward-compatibility enforcement using semantic versioning for every contract update.

# Production Implementation

The ingestion gate runs synchronously at the domain edge before any message is keyed and published. It is the single point where zero-trust is asserted on data shape: nothing is trusted until its topology is proven valid and its CRS is normalized to the declared target. The gate is also the anchor for idempotency — the deterministic schema_version and reprojected geometry it emits feed directly into the idempotency key derived downstream, so a replayed payload always produces the identical key and is skipped.

# Production-ready ingestion gate: CRS & Topology validation
from shapely.geometry import shape, mapping
from shapely.ops import transform as reproject
from pyproj import Transformer


def validate_spatial_payload(payload: dict, target_crs: str = "EPSG:4326") -> dict:
    geom = shape(payload["geometry"])
    if not geom.is_valid:
        raise ValueError("Invalid topology: self-intersection or ring orientation error")

    source_crs_name = (
        payload.get("crs", {}).get("properties", {}).get("name", "EPSG:4326")
    )
    if source_crs_name != target_crs:
        transformer = Transformer.from_crs(
            source_crs_name, target_crs, always_xy=True
        )
        # Reproject every coordinate, then re-emit GeoJSON geometry
        geom = reproject(transformer.transform, geom)
        payload["geometry"] = mapping(geom)
        payload["crs"] = {"type": "name", "properties": {"name": target_crs}}

    payload["schema_version"] = "v2.1.0"
    return payload

Cross-domain sync must guarantee exactly-once semantics to prevent duplicate feature ingestion or topology drift. Idempotency is achieved by deriving deterministic message keys from spatial fingerprints — domain_id:feature_id:crs_hash:version_vector — and producers maintain deduplication tables backed by distributed state stores (RocksDB or a Redis cluster) that track processed sequence IDs. When network partitions occur, the control plane applies conflict resolution using last-write-wins (LWW) with spatial bounding-box precedence, or CRDT-based merge for overlapping geometries. Retry logic uses exponential backoff with jitter, capped at domain-defined SLA thresholds; operations that exceed the synchronous timeout window are routed to asynchronous job queues with explicit status-polling endpoints. Reference patterns for exactly-once delivery are documented in the Apache Kafka documentation.

Zero-trust extends from data shape to routing identity. Synchronization authority is evaluated at the routing layer with attribute-based access control (ABAC), restricting each message to authorized spatial extents, data classifications, and tenant contexts. Open Policy Agent (OPA) sidecars intercept sync requests and evaluate Rego against the envelope metadata before forwarding to any consumer.

# OPA Policy: Restrict sync to authorized administrative boundaries
package spatial.sync

import rego.v1

default allow = false

allow if {
    input.metadata.domain == "planning_dept"
    input.geometry.extent.admin_code in data.authorized_zones
    input.metadata.security_level <= "confidential"
    input.headers["x-mtls-cert-issuer"] == "enterprise-pki"
}

All sync channels enforce mutual TLS (mTLS) with certificate rotation managed via HashiCorp Vault or AWS ACM Private CA. Configuring an individual live feed end-to-end — connector settings, offset management, and partition locality — is covered in Configuring domain sync for real-time spatial feeds.

# Diagnostic Runbook

Clear diagnostic steps are critical when sync pipelines degrade or topology validation fails. Instrument the control plane with distributed tracing via OpenTelemetry and expose domain-scoped metrics over Prometheus endpoints, then work the failure modes in dependency order:

1. Verify sync lag. Query spatial_sync_lag_seconds{domain="target"}. A value above 300 s indicates the consumer cannot keep pace — check partition assignment and consumer-group rebalances before assuming a producer fault.
2. Check contract rejections. Inspect schema_validation_failures_total{reason="crs_mismatch"} and cross-reference registry version drift; a spike usually means a producer shipped a payload outside its declared x-schema-version range.
3. Trace topology errors. Follow trace_id through the ingestion gateway and validate the ring-orientation and self-intersection flags emitted by the validation service against the source geometry.
4. Audit routing decisions. Review OPA decision logs for allow=false events; confirm mTLS certificate validity, the x-mtls-cert-issuer value, and ABAC extent alignment against x-spatial-extent.
5. Inspect idempotency state. Confirm the deduplication store is reachable and that keys are being written; an unreachable Redis or RocksDB node turns exactly-once into at-least-once and produces duplicate features.
6. Validate broker health. Check min.insync.replicas is satisfied and that the spatial Partitioner is mapping extents to the expected partitions; a partition hot-spot manifests as uneven lag across the grid.
7. Replay failed messages. Use the dead-letter queue (DLQ) consumer to reprocess payloads only after the contract alignment or CRS-normalization patch is deployed, so the replay does not re-enter the DLQ.

# SLA Targets & Performance Baselines

These baselines are the contract the control plane is held to. Each metric carries an alert threshold and a defined remediation so on-call response is mechanical rather than improvised.

For high-throughput environments, prioritize low-latency paths for real-time telemetry while batching historical updates during off-peak windows, and apply spatial-index caching, connection pooling, and protocol-buffer serialization to hold routing overhead under the 100 ms target. External consumer traffic should enter through API Gateway Mapping for GIS Services, which translates REST/gRPC calls into internal sync topics while preserving spatial-context headers.

# Governance & Compliance Notes

Governance is enforced as code, not documentation. The Rego policy above is the audited control point: every allow/deny decision is logged with the payload hash, CRS transformations applied, the evaluating policy version, and routing latency, giving compliance reviewers an immutable trail for SLA-breach and access investigations. Audit records must retain the x-idempotency-key and x-schema-version so any propagated change can be reconstructed to its source domain and contract revision.

Jurisdictional constraints bind directly to the spatial envelope. Because x-spatial-extent and admin_code are evaluated at routing time, data-residency rules — keeping a given administrative region’s features inside a regional partition — become an ABAC clause rather than an operational convention. Sync into a restricted extent is denied unless the consuming domain holds an explicit grant, and field-level redaction or geometry generalization is applied when a consumer’s clearance is below the payload’s x-security-level. Lifecycle state from Spatial Product Lifecycle Management gates propagation as well: Deprecated and Archived products are excluded from live sync and surfaced only to consumers that subscribe to historical replay. Validate disaster recovery on a quarterly cadence by simulating control-plane partitioning, verifying state-store replication, and confirming consumers resume from exact watermark offsets without data loss.

# Related

• Federated Ownership & Routing Architecture — parent architecture this protocol operates within
• Schema Contracts for Vector/Tile Data — the contracts validated before sync
• Cross-Domain Routing Strategies — where validated changes are routed
• API Gateway Mapping for GIS Services — external entry point into sync topics
• Configuring domain sync for real-time spatial feeds — end-to-end live-feed setup