gabrielmoreira 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.