hashgraph-online Edit a data contract and test the impact
Change an output-port models/output_ports/v<N>/*.odcs.yaml file, run the contract test, and tell the user whether the change breaks consumers.
This skill operates only on output-port contracts — the spec this data product commits to. Input-port contracts under models/input_ports/ are cached snapshots of upstream's spec and are not editable here; if you want to refresh one (because upstream changed it), run dataproduct-implement instead.
How to run this skill
${PLUGIN_ROOT}below refers to the root of this plugin — the directory that containsskills/. On Claude Code it is set automatically as${CLAUDE_PLUGIN_ROOT}— use that. On any other agent (Codex, Copilot CLI, etc.) it is unset; resolve it as../..relative to thisSKILL.mdfile's directory (i.e. the grandparent ofskills/<this-skill>/).
Plan announcement (before Step 0)
Before running Step 0, print this plan to the user verbatim:
Running datacontract-edit. I'll:
- Locate the output-port contract file under
models/output_ports/v<N>/that matches your request.- Apply the edit in place and show you a unified diff.
- Run
datacontract testagainst the live server to check the change.- Classify each failure as breaking-schema, breaking-quality, additive, or unrelated.
- Report and suggest concrete fixes (no version bump, no v2 directory, no dbt model changes).
Then proceed.
Step 0 — Locate the contract
- Search only
models/output_ports/**/*.odcs.yaml— nevermodels/input_ports/. If the user names an input-port contract, stop and explain it can't be edited here (refresh viadataproduct-implementinstead). - If the user named a contract file or column, find the matching file under
models/output_ports/. - If multiple contracts exist and it's ambiguous, list them and ask which one.
- Read the file and remember the current
modelsblock asBEFORE.
Step 1 — Apply the edit
Edit the ODCS YAML in place using the user's instruction. Keep the change minimal — do not reformat unrelated fields.
Common edits and the right shape:
| User says | What to change |
|---|---|
| "add column X" | Append a field under the relevant model with at least type; set required: false by default unless the user says it's required |
| "remove column X" | Delete the field; this is breaking — flag in Step 4 |
| "rename X to Y" | Rename the field; this is breaking — flag |
| "make X required" | Add required: true; breaking if existing rows can be null |
| "change X type from int to string" | Update type; breaking unless the new type is a strict superset (e.g. int → bigint) |
| "add a unique/not_null/enum check" | Add to the field's quality rules; breaking iff existing data violates the new rule — only Step 2 can tell |
After editing, remember the new models block as AFTER and show the user a unified diff before continuing.
Step 2 — Run the contract test
Run the test with the datacontract CLI against the local contract file:
datacontract test models/output_ports/v<N>/<file>.odcs.yaml --server <server> --logs
- If the contract has more than one server, ask which one (typically
production). Default toallonly if the user explicitly asks. - Use
--logsso failure detail is in the output you read; otherwise the CLI only prints a summary. - If the user wants the report persisted, add
--output ./test-results/junit.xml --output-format junit. - Capture stdout + exit code as
TEST_RESULT. Non-zero exit means at least one rule failed; the log section names the failing field/rule.
Pre-reqs the CLI needs (verify before running, fail fast with a clear message if missing):
uv run --quiet datacontract --versionsucceeds from the project root. If it fails, runuv syncand retry. Invoke asuv run datacontract test …for every CLI invocation in this skill.- The chosen server's credentials available as env vars per the ODCS server block (e.g.
DATACONTRACT_SNOWFLAKE_USERNAME/..._PASSWORD, orDATACONTRACT_DATABRICKS_TOKEN). Tell the user which env vars are missing — do not try to source them yourself.
Do not use the platform's server-side contract-test endpoint from this skill. The local datacontract CLI runs against the edited file and gives line-level failure detail; testing the published version on the server would test the previous contract, which defeats the point of testing the edit.
Step 3 — Classify the outcome
Group every failure into one of these buckets:
| Bucket | Examples | Severity |
|---|---|---|
| Breaking — schema | column removed, type narrowed, column renamed | High — bump major version, deprecate old port |
| Breaking — quality | new not_null/unique/enum rule violated by existing data |
High — clean data first, then re-test |
| Non-breaking — additive | new optional column, widened type, loosened rule | Low — minor version bump |
| Test failure unrelated to the edit | flaky source, infra error, unchanged rule failing | Investigate separately |
For each failure, name the exact field/rule and which bucket it falls into. Don't lump them together.
Step 4 — Report and suggest fixes
End with this two-part recap. The Status column uses the shared enum (created, updated, already present, deferred, skipped), and below it a classification table covers any test failures.
Part 1 — outcome table.
| Artifact | Status | Details |
|---|---|---|
| Contract file | updated | models/output_ports/v<N>/<file>.odcs.yaml — show the unified diff inline |
| Contract test | … | pass, fail (<N> failures), or not run (missing creds) — name the server |
| Breaking — schema | … | count of failures in this bucket, or "—" |
| Breaking — quality | … | count of failures in this bucket, or "—" |
| Non-breaking — additive | … | count of changes in this bucket, or "—" |
| Test failures unrelated to the edit | … | count, or "—" |
| Recommended version bump | … | patch / minor / major based on the edit |
For the four "bucket" rows, leave Status = — and put the failure count + a one-line bucket description in Details.
Part 2 — next steps. Per failure, give a concrete fix suggestion:
- Schema breaking: bump to a new output port version (
models/output_ports/v2/), keep v1 alive, add a deprecation note in<id>.odps.yaml. - Quality breaking: SQL snippet to find the offending rows so the user can decide whether to clean, accept, or relax the rule.
- Additive: bump the contract's
versionminor, no consumer impact. - If no failures, recommend the version bump (patch for cosmetic, minor for additive, major for breaking even when the test happened to pass).
Do not auto-bump the contract version, do not create v2/ directories, and do not modify dbt models. Surface the recommendation; let the user decide.
Constraints
- Always run the test after every edit. A passing edit looks the same as a breaking edit until you run it.
- Don't edit the dbt models in this skill. Changing the contract is a separate decision from changing the implementation. If the user wants both, run
dataproduct-implementafter this skill. - Don't fetch a remote version of the contract — operate on the local file. If the user wants to pull the published version, ask them to do that explicitly first (it can be a one-line
entropy-data datacontracts get <id> -o yamlredirected to the file). - Idempotent: re-running with the same edit should be a no-op (same diff = empty, same test = same result).
Source: hashgraph-online/awesome-codex-plugins → plugins/entropy-data/dataproduct-builder-dbt/skills/datacontract-edit/SKILL.md