The data mesh decision record: why the domain ownership model you chose determines your cross-domain data contract debt and your federated governance failure surface

A 55-person B2B SaaS company built a project management platform. In month eight, after the analytics complexity had grown beyond what the core engineering team could maintain alongside feature development, the company created a dedicated data platform team. The founding session for the data platform organization documented "data platform team owns the reporting pipeline and dashboard infrastructure." The source-of-truth data lived in PostgreSQL tables owned by the product engineering teams. The data platform team wrote ETL jobs that read from database replicas and loaded the results into a data warehouse. The founding session documented the ownership assignment; it did not document the schema change notification protocol.

Fourteen months after the data platform was established, the subscriptions service team added a new value to the subscription_status enum: GRACE_PERIOD, inserted between ACTIVE and PAST_DUE to represent accounts that had missed a payment but were within a 7-day grace window before enforcement. The subscriptions team created a database migration, updated their service, tested against staging, and deployed. The change was purely within the subscriptions service's domain. There was no notification to the data platform team because no notification protocol existed — the founding session had never specified that upstream schema changes required downstream notification.

The data platform ETL that read from the subscriptions table had been written when the enum had five values. The transform step mapped each enum value to an integer code using a CASE expression: WHEN 'ACTIVE' THEN 1 WHEN 'TRIAL' THEN 2 WHEN 'PAST_DUE' THEN 3 WHEN 'CANCELLED' THEN 4 WHEN 'CHURNED' THEN 5 ELSE NULL END. The GRACE_PERIOD value fell through to NULL. The downstream aggregate queries filtered on status_code IS NOT NULL. All GRACE_PERIOD subscriptions were silently excluded from every revenue dashboard, every cohort analysis, and every subscription count query. The ETL ran successfully — no errors, no alerts. The pipeline health dashboard showed green.

For seven weeks, the revenue dashboard showed subscription counts and MRR that excluded all GRACE_PERIOD accounts. At the end of Q3, the finance team ran a reconciliation between the Stripe billing export and the data warehouse dashboard. The Stripe export showed 847 subscriptions in GRACE_PERIOD status representing $31,400 in monthly recurring revenue that did not appear in the revenue dashboard. The Q3 board presentation had cited retention cohort numbers that were incorrect because the cohort analysis treated GRACE_PERIOD accounts as churned. Investigation took four days. The fix was one line: adding WHEN 'GRACE_PERIOD' THEN 6 to the CASE expression. But the data platform team then had to audit eight other ETL pipelines that read from enum columns in product-owned tables, because the same class of silent drop was possible in any pipeline that mapped enum values to integers without handling unknown values as an error. Three of the eight pipelines had the same pattern. The founding data platform session documented "data platform team owns the reporting pipeline" but never specified who was responsible for notifying the data platform team before upstream schemas changed, what constituted a breaking change in a source table, or what the ETL's behavior must be when it encountered an unexpected value — fail loudly or silently skip the row.

A 130-person enterprise SaaS company that built B2B workflow automation tooling adopted data mesh in year three, when the engineering organization had grown to eight distinct product domains: customers, workflows, integrations, billing, notifications, entitlements, analytics, and infrastructure. The founding session for the data mesh initiative documented "domain-oriented ownership, domain teams own their data products, federated governance committee meets monthly to coordinate cross-domain concerns." Each domain team exposed their data as read-optimized tables in a shared Snowflake data warehouse. The founding session drew the domain boundaries and assigned ownership. It did not specify the canonical entity identifier that cross-domain analytics would require.

Sixteen months after the data mesh launch, the revenue analytics team needed to build a workflow adoption cohort analysis: for each customer segment, what fraction of workflows created in the first 30 days remained active at 90 days? The analysis required joining data from three domain data products. The customers data product, owned by the customers domain team, used customer_uuid — a UUID v4 generated at account creation by the platform's identity service — as its primary key. The workflows data product, owned by the workflows domain team, used workflow_id and org_id as its join keys, where org_id was an integer from the legacy Salesforce-based CRM system that had been in place before the platform's UUID-based identity system existed; the workflows service had been built against that legacy integer identifier and had never been migrated to the platform UUID. The billing data product, owned by the billing domain team, used billing_account_id as its primary key — a Stripe customer ID with an internal organization suffix appended during provisioning, formatted as cus_abc123_ORG-4891.

Three different key spaces: UUID, integer, and Stripe-prefixed string. There was no cross-domain join key. The revenue analytics team filed requests with all three domain teams asking each to expose a shared canonical identifier. The customers domain team responded that their data product was already correct — customer_uuid was the platform's canonical identifier and other teams should map to it. The workflows domain team responded that migrating from org_id to customer_uuid was a significant engineering investment with no workflows-domain business justification. The billing domain team responded that their data product was a projection of the Stripe billing model and billing_account_id was what Stripe used — changing it would require a migration across all billing webhook handlers. Each position was defensible from within the domain. None was compatible with the cross-domain analytics use case.

The federated governance committee was convened for an emergency session. Over the following nine weeks, the committee discussed whether the canonical identifier should be customer_uuid (the customers team's position), a new synthetic bridging key (the integrations team's proposal), or a phased migration with a mapping table as an intermediate (the data platform team's recommendation). The committee had no authority to compel any domain team to change their data product schema. Attendance was voluntary. Two domain team leads missed three of the four sessions. The outcome was a recommendation, not a decision. An ad-hoc analytics engineer, impatient with the process, built a cross-domain bridge table by matching records on email address (normalized to lowercase) across all three domains and joining with a three-year-old Confluence table that had been created during a Salesforce migration that mapped legacy integer org IDs to the platform's UUIDs. The bridge was unreliable — email addresses changed when users updated their profiles, and the Confluence mapping covered only 73% of the organizations because 27% had been created after the Salesforce migration ended. The analytics engineer used the bridge for the cohort analysis, marked the results as "provisional — cross-domain identity resolution incomplete," and published them anyway because the quarter-end deadline was three weeks away. The founding data mesh session documented "domain ownership, federated governance committee." It never specified the canonical entity identifier for cross-domain references, the governance mechanism that could compel domain teams to implement cross-domain identifiers, or the SLA that data products were required to meet and the escalation path when they did not.

Structural properties set by the data architecture design decision

Three structural properties are determined when a team decides how to organize ownership of their data assets. None appear explicitly in the founding sessions that assign data platform ownership, draw domain boundaries, or establish governance committees — they are the operational consequences of choices made under the pressure of scaling an engineering organization beyond the point where one team can own all data infrastructure.

Property 1: The data product ownership model and the schema change notification contract. In a monolith, schema changes are visible to all code before deployment: the same repository, the same build pipeline, the same database migration that runs at deploy time. A developer changing a column name sees immediately which query strings break. In a data mesh, the domain team that owns the upstream source and the data platform team that reads from it are organizationally separated, and the schema change is invisible to the downstream consumer until either the pipeline runs and encounters the new schema or — in the silent-drop failure mode — the pipeline runs successfully but produces incorrect results.

The notification contract must specify three things. First, the breaking change definition: which changes require prior notification to downstream consumers and which do not. Adding a NOT NULL column to a source table is a breaking change for any ETL that uses INSERT INTO target SELECT * FROM source. Changing an enum value set is a breaking change for any ETL that maps enum values explicitly. Renaming a column is a breaking change for any query that references the column by name. Adding a nullable column is typically non-breaking if the consumer is designed to handle NULL in that position. The distinction matters because it determines which changes trigger the notification protocol and which can be deployed without coordination. If the definition is "any schema change requires notification," developers will route around the protocol on changes they consider minor. If the definition enumerates the specific change types that are breaking, the protocol is actionable.

Second, the notification timeline: how far in advance of deployment must the notification be sent, what must it include, and who receives it. A 30-day minimum lead time for breaking changes is a common floor for data products with committed SLAs — it gives consumers enough time to update their pipelines before the breaking change reaches production. The notification must include the specific fields changing, the target deployment date, and a migration guide describing how consumers should update their pipelines. Recipients must be all registered consumers of the data product, not just the data platform team — any team that reads directly from the source table is a consumer with the same dependency.

Third, the consumer behavior on unexpected values: the ETL or query that encounters a value outside its contracted schema must fail loudly, not silently. "Fail loudly" means the pipeline run fails with an explicit error message identifying the unexpected value and the field, the failure triggers an alert to the pipeline owner and the data product owner, and no partial results are written to the downstream table until the pipeline is updated to handle the new value. Silent skip — mapping unexpected values to NULL or zero — is the default behavior of most ETL frameworks and is the source of the seven-week silent-drop failure above. The observability strategy decision record documents the alerting infrastructure; data pipeline failures must produce structured alerts with the specific value and field that caused the failure, not generic "pipeline failed" notifications, so that the pipeline owner and the data product owner can coordinate a resolution without a manual investigation step.

Property 2: The cross-domain identity resolution model and the join key surface. The cross-domain join key problem is the structural tax of domain decomposition. Each domain assigns identifiers for its own operational use — integer primary keys from legacy systems, UUIDs generated by the platform identity service, third-party system IDs from billing or CRM providers. The cross-domain analytics use case, which is always present in any company that wants to understand customer behavior across its product surface, requires a path from one domain's key space to another's. If that path is not specified in the data mesh founding ADR, it will be discovered at the point of the first cross-domain analytics requirement and resolved ad hoc — with the email-address matching and Confluence mapping table approach that produces unreliable results and no ownership.

The canonical identifier approach is the lowest-cost solution at steady state: establish a universal entity identifier for each major entity type (customer, organization, user, product, order) before domain decomposition, require all data products to expose this identifier, and treat any data product that cannot expose the canonical identifier as owing a migration debt with a documented resolution timeline. The canonical identifier must be generated by a platform identity service that all domain services call at entity creation time — not derived from domain-local attributes like email address, which changes, or legacy system IDs, which are not universal. New data products built after the canonical identifier is established use it as their primary key. Legacy data products that were built before the canonical identifier must add it as a new field via a non-breaking schema addition (nullable column, populated by a backfill) and document the fraction of existing records that could not be backfilled and why.

The cross-domain bridge approach is the correct fallback when canonical identifiers cannot be retrofitted in a reasonable timeframe. The bridge table maps between the per-domain key spaces and is owned by a platform team (not an analytics team) with a data product contract that specifies its freshness SLA, its correctness SLA (the fraction of entity records that have a complete mapping across all key spaces), and its schema versioning policy. The bridge is updated automatically from authoritative sources — the platform identity service, the legacy system migration tables, the billing provider's API — not from email matching or manual exports. When a domain-local identifier changes (the workflows domain migrates from integer org_id to UUID), the bridge update is part of the migration scope, not an afterthought discovered when the analytics team finds the bridge is broken. The data quality monitoring decision record documents the quality gate model; the cross-domain bridge must have correctness monitoring that alerts when the mapping coverage drops below a threshold — "73% of organizations have a complete cross-domain mapping" is not a stable steady state, it is an ongoing data quality problem that must be tracked and owned.

Property 3: The federated governance model and the SLA accountability surface. Federated governance as "a committee meets monthly" is not a governance mechanism — it is a coordination forum. The distinction matters when a cross-domain concern requires a domain team to do work that has no direct business value for that domain. No committee can compel a domain team to migrate from integer org_id to customer_uuid if the domain team's roadmap is full of domain-specific feature work and the cross-domain identifier is only needed by the analytics team. The governance model collapses at exactly the moment it is most needed: when coordinating cross-domain changes.

A governance mechanism has three components that a coordination forum does not. The first is enforcement authority: who can compel a domain team to change its data product schema, add a cross-domain identifier, or meet a specific SLA, and what is the consequence of refusing. In most organizations, enforcement authority must come from a level above the domain team — an engineering director or VP who owns both the domain team's roadmap and the data platform team's requirements. The federated governance ADR must name the person or role that holds enforcement authority, not describe a committee that can only recommend. The second is data product registration requirements: domain teams cannot expose a data product to consumers until the data product contract is registered in the governance platform, reviewed against a quality checklist (canonical identifier exposed, schema versioned, SLAs specified, consumer notification protocol documented), and assigned a named owner. Unregistered data products are invisible to the self-serve data platform. Registration is the enforcement lever that prevents domain teams from publishing data products without contracts — it is not a manual review step but a pipeline gate. The third is SLA breach escalation: the governance platform monitors freshness and correctness SLAs for all registered data products automatically and escalates breaches without requiring a committee session. First-level escalation goes to the named data product owner within 15 minutes of a breach. If unresolved, escalation proceeds to the domain team lead at 1 hour, then to the domain team's engineering manager at 4 hours. The escalation path is specified in the data mesh ADR and does not depend on the committee's meeting cadence.

What the founding session records and what it omits

The founding data architecture session typically records the ownership assignment ("data platform team owns the reporting infrastructure," "domain teams own their data products"), the domain boundaries ("customers domain, workflows domain, billing domain"), and sometimes the tooling choice ("Snowflake for the data warehouse, dbt for transforms, Airflow for orchestration"). What it does not record is the schema change notification contract (breaking change definition, notification timeline, consumer registry), the canonical entity identifier per entity type and the cross-domain identity resolution model, the data product SLA specification (freshness, correctness, availability), the consumer behavior on unexpected values (fail loudly or silently skip), or the governance enforcement mechanism that gives the governance model authority when a domain team's data product fails its downstream consumers.

The omissions are consequential because they become load-bearing architectural constraints as the organization scales. The absence of a schema change notification contract means every ETL pipeline is a latent silent-drop failure waiting for the next upstream enum extension or column rename — and the failure is invisible until a downstream reconciliation discovers the discrepancy weeks later. The absence of a canonical entity identifier means the first cross-domain analytics use case requires an ad-hoc identity resolution effort that produces an unreliable bridge with no owner and no SLA — and every subsequent cross-domain analytics requirement faces the same problem. The absence of a governance enforcement mechanism means the governance committee can only recommend, not compel, which produces coordination without accountability when domain teams have competing priorities.

The data mesh decision record does not need to be comprehensive. It needs to answer five questions: what are the domain boundaries and who owns each data product, what is the data product contract format including the breaking change definition and consumer notification protocol, what is the canonical entity identifier for each entity type and how are cross-domain joins resolved, what are the data quality SLAs and the escalation path when they are missed, and what is the self-serve data platform infrastructure that domain teams use to register and publish their data products. Five answers written down in the founding session avoid months of silent pipeline failures, cross-domain identity crises, and governance committee deadlocks that each trace back to a decision that was made but not recorded.

The WhyChose decision extractor finds these founding data architecture sessions in your ChatGPT and Claude export — the "who should own reporting?" conversation, the "how do we organize our data teams?" thread, the "what should our data platform look like?" research session. It extracts the decision and the trade-off that was considered, without the surrounding context of Slack cross-posts and meeting follow-up threads that buries the actual choice in forty-five messages of clarification.

The five ADR sections for a data mesh decision

Section 1: Domain boundary definition and data product ownership model. Specify the domain boundaries: the bounded contexts that define each domain's scope, the entity types each domain owns (creates, updates, and is the authoritative source for), and the data products each domain is responsible for exposing. The domain boundary definition must include the boundary arbitration rule — when an entity or event could plausibly belong to two domains, which domain owns it and why. Specify the ownership model: each data product has a named owner (a team, not an individual), the owner is responsible for the data product contract, the SLA, and the consumer notification protocol. Ownership is a commitment, not a label — the owner is the escalation point when the data product fails its SLA and the approver when a consumer wants to use the data product. The event-driven architecture decision record documents the domain event model; in a data mesh, domain events are the source of truth for data products in streaming architectures — the data product is derived from the domain's event stream, not from a direct read of the operational database replica. Specifying which data products derive from events versus from database reads determines the freshness ceiling (event-derived products can achieve sub-minute freshness; database-replica-derived products are bounded by the replica lag and the ETL cadence) and the schema change surface (event schema changes require coordination with the schema registry; database replica reads require the notification protocol described in Section 2).

Section 2: Data product contract: schema versioning, breaking change definition, and consumer notification protocol. Specify the data product contract format: schema version (semantic version, incremented on any change), field-level specification (name, type, nullable, enum value set if applicable, description), and the SLA fields (freshness commitment, correctness commitment, availability commitment). Specify the breaking change definition: changes that require a contract version bump and consumer notification before deployment. Common breaking change categories include removing a field, renaming a field, changing a field's type, changing a field from nullable to NOT NULL, adding a value to an enum if consumers are contractually required to handle a fixed enum set, and removing an enum value. Non-breaking changes — adding a nullable field, adding an enum value if consumers are contractually required to handle unknown values by failing loudly — may be deployed without prior notification but must be reflected in a contract version bump within 24 hours. Specify the consumer registry: the mechanism by which consumers register their dependency on a data product. Registration is the enforcement lever — consumers who are not registered are not in the notification distribution and are not eligible to file SLA breach escalations. Specify the notification protocol: who receives notifications (all registered consumers), what the notification must include (field changes, deployment timeline, migration guide), and the minimum notification lead time by change severity (30 days for breaking changes, 7 days for non-breaking additions, 24 hours for emergency patches). Specify the consumer behavior requirement: all consumers of a data product must fail loudly — stopping the pipeline run and generating an alert — when they encounter a field value outside the contracted schema. The API schema design decision record documents schema design principles; data product schemas share the same backward-compatibility constraints as API schemas, and the same principles apply: additions are safe, removals are breaking, renames are breaking, type changes are breaking. The API versioning decision record documents the versioning policy; data product schema versions follow the same semantic versioning conventions as API versions, with the same major/minor/patch semantics.

Section 3: Cross-domain identity resolution model and canonical entity identifier specification. Enumerate the entity types that appear in more than one domain's data products. For each entity type, specify the canonical identifier: the unique identifier that all domains use when referencing this entity in cross-domain contexts. The canonical identifier must be generated by the platform identity service at entity creation time, stable (does not change when the entity's attributes change), and universal (used by all new services from the date this ADR is ratified). For each entity type, enumerate the existing per-domain identifiers that are currently used in production data products: the legacy integer IDs, the third-party system IDs, the domain-specific composite keys. For each existing per-domain identifier, specify the migration plan to add the canonical identifier as a non-breaking addition to the data product schema, the backfill completion timeline, and the fraction of historical records that cannot be backfilled (with documented reasons). For entity types where the canonical identifier cannot be retrofitted in the current quarter, specify the cross-domain bridge: the table that maps between per-domain key spaces, the owner, the update mechanism (automated ETL from authoritative sources — not email matching or manual exports), the freshness SLA, the correctness SLA (percentage of entity records with a complete mapping), and the schema versioning policy. Specify the downstream analytics requirement for the bridge: what is the minimum correctness threshold below which cross-domain analytics results must be marked as provisional and cannot be used in board reporting. The data retention decision record documents the retention policy per data domain; the cross-domain bridge table's retention policy must cover the maximum retention period of any of the data products it maps between — if the billing domain retains billing records for seven years, the bridge must retain billing-to-customer mappings for seven years even if the customers domain's data product has a shorter retention period.

Section 4: Data quality SLA specification and federated governance enforcement mechanism. Specify the SLA for each registered data product: the freshness SLA (maximum lag from upstream event to data product update at p99, e.g., 30 minutes for hourly-cadence products, 1 hour for daily-cadence products, 5 minutes for streaming products), the correctness SLA (maximum allowable divergence from the authoritative source measured by the data product's correctness check, e.g., row count within 0.1% of source, aggregate value within 0.5% of source), and the availability SLA (fraction of time the data product is queryable without error, e.g., 99.5% monthly). Specify the SLA monitoring model: the governance platform runs SLA checks on a cadence appropriate to the product's freshness commitment (every 5 minutes for streaming products, every 15 minutes for hourly products, every 2 hours for daily products). The data quality monitoring decision record documents the quality gate model for data pipelines; data product SLA monitoring is a specialized application of the general data quality monitoring model, with the addition of cross-domain correctness checks that compare the data product's key counts against the source domain's authoritative count. Specify the SLA breach escalation path: first escalation to the data product owner (15 minutes after breach detection), second escalation to the domain team lead (1 hour after breach detection if unresolved), third escalation to the domain team's engineering manager (4 hours after breach detection if unresolved), emergency escalation to the enforcement authority named in Section 1 for persistent or recurring breaches. Specify the governance enforcement mechanism: data product registration is required before a data product is discoverable in the self-serve data platform; registration requires schema version, SLA specification, owner designation, and consumer notification protocol; the CI/CD pipeline for domain services includes a check that detects schema changes to data product sources and fails the build if the contract version has not been updated; enforcement authority for cross-domain coordination disputes rests with the named role specified in this section, not with the governance committee. The CI/CD pipeline decision record documents the pipeline architecture; the data product contract CI check is a pipeline gate, not a manual review step — it runs on every pull request that touches a source table used by a registered data product and fails the build if the contract is not updated.

Section 5: Self-serve data platform infrastructure: storage model, compute model, and access control. Specify the data warehouse storage model: the cloud data warehouse (Snowflake, BigQuery, Redshift, Databricks) and the rationale, the data product storage structure (one schema per domain, one table or view per data product, no cross-schema JOINs in registered data products), and the data product naming convention (domain_name.entity_type_v{major_version}, e.g., customers.customer_profiles_v2, workflows.workflow_events_v1). Specify the compute model: the orchestration platform for data product refresh jobs (Airflow, dbt Cloud, Dagster), the ownership of orchestration configuration (domain teams own the DAGs that refresh their data products, the data platform team owns the orchestration infrastructure), and the failure notification model (failed DAG runs alert the data product owner, not the data platform team — the data platform team is responsible for orchestration infrastructure availability, not for individual product freshness). Specify the access control model: who can read which data products, the mechanism by which a new consumer team requests access (a pull request to the consumer registry, reviewed by the data product owner), the access review cadence (quarterly review of all active consumer registrations by the data product owner), and the access revocation process when a team no longer consumes a data product. The authorization model decision record documents the general permission model; data product access control is a specialized application — consumers are teams rather than individual users, permissions are read-only, and access is scoped to schema-level rather than row-level unless the data product contains sensitive data requiring row-level security. Specify the self-serve onboarding contract: what documentation a new data product must provide before registration (schema documentation, field definitions, known data quality limitations, example queries, SLA commitment), what documentation a new consumer team must provide before access is granted (use case description, downstream data products or dashboards that depend on this product, SLA requirements from the downstream use case), and how the onboarding process is enforced (automated checklist in the registration platform, not a manual review by the governance committee). The database partitioning decision record documents the storage partitioning model; time-series data products (event streams, activity logs, audit trails) benefit from date-based partitioning in the data warehouse for both query pruning and data lifecycle management — the partitioning key must be specified in the data product contract so consumers can write partition-pruning queries, and the partition count ceiling (the point at which partition overhead exceeds the pruning benefit for the most common query patterns) must be documented before the data product accumulates enough partitions to hit it.

Further reading

• The event-driven architecture decision record — domain events as the source of truth for data products in streaming architectures; the data product schema is derived from the domain event schema and inherits its change management constraints.
• The API versioning decision record — semantic versioning principles for data product schemas; data product schema versions follow the same major/minor/patch conventions as API versions with the same breaking change semantics.
• The API schema design decision record — backward-compatibility principles that apply equally to data product schemas: additions are safe, removals are breaking, renames are breaking, type changes require versioning.
• The data quality monitoring decision record — the quality gate model for data pipelines; data product SLA monitoring extends the general quality model with cross-domain correctness checks and governance-escalation-integrated breach alerting.
• The data retention decision record — retention policies per data domain; the cross-domain bridge table must retain mappings for the maximum retention period of any data product it connects.
• The authorization model decision record — the permission model for data product access control; consumers are teams with read-only schema-level permissions, access is granted via the consumer registry, revocation is governed by a quarterly review cadence.
• The observability strategy decision record — the alerting infrastructure for data pipeline failures; pipeline alerts must include the specific unexpected field value and the data product name so the product owner and the domain team can coordinate without a manual investigation step.
• The CI/CD pipeline decision record — the pipeline architecture that data product contract enforcement gates hook into; the schema-change detection check is a pipeline gate that fails the build when a source table change is not reflected in a contract version bump.
• The database partitioning decision record — the storage partitioning model for time-series data products; partitioning key specification in the data product contract enables consumers to write partition-pruning queries, and the partition count ceiling must be documented before the data product accumulates enough partitions to degrade query performance.
• WhyChose decision extractor — finds the founding "who should own reporting?" and "how do we organize our data teams?" sessions in your ChatGPT or Claude export and extracts the decision and the trade-offs that were considered, without the surrounding context of architecture discussion threads that buries the actual choice.