data-contract

Data Contract Skill

Most data outages are a producer changing a column without telling anyone downstream. A data contract

fixes that: it's an explicit, versioned agreement on the schema, semantics, and quality guarantees of

a dataset/event/stream, with an owner and a breaking-change policy. This skill writes one, so producers

and consumers share a single source of truth and changes can't silently break pipelines.

Required Inputs

Ask for these only if they aren't already provided:

• The data asset — the table, event, topic, or API, and what it represents.
• Producer & consumers — who owns it, who depends on it.
• Schema — fields, types, and which are required; the semantics of the tricky ones.
• Quality expectations — freshness (how current), completeness, valid ranges, uniqueness.

Output Format

Data Contract: [asset] v[x.y]

Producer (owner): [team] · Consumers: [teams/systems] · Status: active

1. Schema — every field: name · type · required? · description/semantics · constraints (enum, range, format).

| field | type | required | constraint | meaning |

|---|---|---|---|---|

2. Semantics — the non-obvious meanings: timezone of timestamps, currency/units, what null means, how late-arriving data is handled, the grain/uniqueness.

3. Quality SLAs — the guarantees, measurable: freshness (e.g. updated by 06:00 UTC daily), completeness (no missing required fields), validity (values in range), uniqueness (PK unique). These are what consumers can rely on.

4. Ownership & support — who owns it, where to raise issues, on-call/response expectations.

5. Versioning & breaking changes — semver for the schema; what counts as breaking (removing/renaming a field, tightening a type, changing semantics) vs. non-breaking (adding optional fields); deprecation window before a breaking change ships.

6. Change process — how a change is proposed, who must sign off (affected consumers), and the notice period.

Quality Checks

• [ ] Every field has a type, required-flag, and clear semantics (esp. timezone/units/null meaning)
• [ ] Quality SLAs are measurable (a number/time), not "should be fresh"
• [ ] Breaking vs. non-breaking changes are explicitly defined
• [ ] There's a deprecation window and a sign-off process for breaking changes
• [ ] An owner and an issue/escalation path are named

Anti-Patterns

• [ ] Do not leave semantics implicit — undocumented timezone/units/null handling is the #1 silent data bug
• [ ] Do not write vague SLAs — "fresh and accurate" is unenforceable; give times and thresholds
• [ ] Do not allow breaking changes without notice — a deprecation window + consumer sign-off is the whole point
• [ ] Do not skip ownership — an unowned dataset has no one to hold to the contract
• [ ] Do not version informally — schema changes need semver so consumers know what broke

Based On

Data-contract practice — schema + semantics + measurable quality SLAs, semantic versioning, and producer/consumer change governance.