data-contract-testing-with-schema-registry

Name: data-contract-testing-with-schema-registry
Author: vaquarkhan

19stars4forks

How to install data-contract-testing-with-schema-registry?

vaquarkhan/data-engineering-agent-skills/data-contract-testing-with-schema-registry

$npx -y skills add vaquarkhan/data-engineering-agent-skills --skill data-contract-testing-with-schema-registry

Installs into the current project.

Summary

Guides agents through data-contract testing using schema registries and compatibility checks. Use when validating event contracts, stream schema evolution, consumer compatibility, or release gates for schema-managed systems.

Files · 1

View on GitHub

SKILL.md

1	# Data Contract Testing With Schema Registry
2
3	## Overview
4
5	Use this skill when contracts must be tested through registry-backed compatibility rules, not only by convention. It helps agents make event contract validation a blocking part of build and release behavior with automated testing, consumer impact analysis, and evidence-driven release gates.
6
7	## When to Use
8
9	- testing event contract changes before production release
10	- validating schema compatibility as part of CI/CD pipelines
11	- coordinating producer and consumer schema evolution across teams
12	- enforcing registry-backed contract quality gates before deployment
13	- building release evidence that proves schema safety
14
15	Do not use this when schemas are not managed through a registry or when the system has no shared event contracts.
16
17	## Workflow
18
19	1. Define the contract and compatibility target per subject.
20	Include:
21	- which schema registry subjects are in scope
22	- the compatibility level required: `BACKWARD`, `FORWARD`, `FULL`, or `TRANSITIVE` variants
23	- who owns the contract (producing team, platform team, or shared)
24	- which consumers depend on each subject and their minimum supported version
25
26	2. Implement contract tests in CI.
27	- register the proposed schema against the registry's compatibility endpoint
28	- use the registry's `/compatibility` API to check before merging
29	- fail the build if compatibility is violated
30	- produce test output showing which rules passed or failed
31	- run tests against both the latest registered version and specific consumer versions
32
33	3. Test representative producer and consumer scenarios.
34	- serialize sample records with the new schema and deserialize with the old
35	- verify that default values produce correct behavior for removed or added fields
36	- test edge cases: null handling, enum additions, nested record changes
37	- for Protobuf: test field number stability and reserved field behavior
38	- for Avro: test union type evolution and logical type compatibility
39
40	4. Validate downstream consumer impact before release.
41	- identify all registered consumers of the subject
42	- test that each consumer's current schema can read the proposed producer schema
43	- document which consumers need upgrades for breaking changes
44	- define the deployment order: consumer upgrade before or after producer change
45	- communicate schema changes through established team channels
46
47	5. Tie contract test results to release gates.
48	- schema compatibility check must pass before deployment proceeds
49	- produce structured evidence (JSON report) of compatibility test results
50	- store evidence alongside the release artifact for audit
51	- block production deploys on compatibility failures — no manual overrides without review
52	- include contract test results in pull request checks
53
54	6. Plan for contract migrations and breaking changes.
55	- when breaking changes are necessary, define a migration plan
56	- create a new subject or version namespace for the breaking schema
57	- run both old and new contracts in parallel during migration
58	- define a deprecation timeline for the old contract
59	- document the consumer migration path with explicit deadlines
60
61	## Common Rationalizations
62
63	\| Rationalization \| Reality \|
64	\| --- \| --- \|
65	\| "We check compatibility manually before releasing." \| Manual checks are inconsistent and skip edge cases. Automated registry-backed testing catches issues that humans miss under time pressure. \|
66	\| "Adding a field is always safe." \| Adding a required field without a default breaks backward compatibility. Adding an optional field is safe only if consumers handle absence correctly. \|
67	\| "We only have one consumer so contract testing is overhead." \| Consumers multiply over time. Establishing contract testing early prevents breaking changes from accumulating technical debt. \|
68	\| "The registry will reject incompatible schemas anyway." \| Registry rejection at deploy time is too late. Testing in CI catches issues before code is merged and before release pressure builds. \|
69
70	## Red Flags
71
72	- no contract tests in CI — compatibility is checked only at deploy time
73	- proposed schemas are registered directly without prior compatibility validation
74	- consumer dependency map does not exist — nobody knows who reads the events
75	- breaking changes are deployed with "we'll fix consumers later" attitude
76	- test output is not stored — no evidence trail for audits
77	- compatibility policy is set to `NONE` in production subjects
78	- contract test failures are routinely overridden without review
79	- migration plans for breaking changes have no timeline or consumer notification
80
81	## Verification
82
83	- [ ] Compatibility targets are defined per subject an

People who liked this also viewed

6 picks

Type

data-contract-testing-with-schema-registry

19stars4forks

View on GitHub

How to install data-contract-testing-with-schema-registry?

vaquarkhan/data-engineering-agent-skills/data-contract-testing-with-schema-registry

$npx -y skills add vaquarkhan/data-engineering-agent-skills --skill data-contract-testing-with-schema-registry

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Data Contract Testing With Schema Registry
2
3	## Overview
4
5	Use this skill when contracts must be tested through registry-backed compatibility rules, not only by convention. It helps agents make event contract validation a blocking part of build and release behavior with automated testing, consumer impact analysis, and evidence-driven release gates.
6
7	## When to Use
8
9	- testing event contract changes before production release
10	- validating schema compatibility as part of CI/CD pipelines
11	- coordinating producer and consumer schema evolution across teams
12	- enforcing registry-backed contract quality gates before deployment
13	- building release evidence that proves schema safety
14
15	Do not use this when schemas are not managed through a registry or when the system has no shared event contracts.
16
17	## Workflow
18
19	1. Define the contract and compatibility target per subject.
20	Include:
21	- which schema registry subjects are in scope
22	- the compatibility level required: `BACKWARD`, `FORWARD`, `FULL`, or `TRANSITIVE` variants
23	- who owns the contract (producing team, platform team, or shared)
24	- which consumers depend on each subject and their minimum supported version
25
26	2. Implement contract tests in CI.
27	- register the proposed schema against the registry's compatibility endpoint
28	- use the registry's `/compatibility` API to check before merging
29	- fail the build if compatibility is violated
30	- produce test output showing which rules passed or failed
31	- run tests against both the latest registered version and specific consumer versions
32
33	3. Test representative producer and consumer scenarios.
34	- serialize sample records with the new schema and deserialize with the old
35	- verify that default values produce correct behavior for removed or added fields
36	- test edge cases: null handling, enum additions, nested record changes
37	- for Protobuf: test field number stability and reserved field behavior
38	- for Avro: test union type evolution and logical type compatibility
39
40	4. Validate downstream consumer impact before release.
41	- identify all registered consumers of the subject
42	- test that each consumer's current schema can read the proposed producer schema
43	- document which consumers need upgrades for breaking changes
44	- define the deployment order: consumer upgrade before or after producer change
45	- communicate schema changes through established team channels
46
47	5. Tie contract test results to release gates.
48	- schema compatibility check must pass before deployment proceeds
49	- produce structured evidence (JSON report) of compatibility test results
50	- store evidence alongside the release artifact for audit
51	- block production deploys on compatibility failures — no manual overrides without review
52	- include contract test results in pull request checks
53
54	6. Plan for contract migrations and breaking changes.
55	- when breaking changes are necessary, define a migration plan
56	- create a new subject or version namespace for the breaking schema
57	- run both old and new contracts in parallel during migration
58	- define a deprecation timeline for the old contract
59	- document the consumer migration path with explicit deadlines
60
61	## Common Rationalizations
62
63	\| Rationalization \| Reality \|
64	\| --- \| --- \|
65	\| "We check compatibility manually before releasing." \| Manual checks are inconsistent and skip edge cases. Automated registry-backed testing catches issues that humans miss under time pressure. \|
66	\| "Adding a field is always safe." \| Adding a required field without a default breaks backward compatibility. Adding an optional field is safe only if consumers handle absence correctly. \|
67	\| "We only have one consumer so contract testing is overhead." \| Consumers multiply over time. Establishing contract testing early prevents breaking changes from accumulating technical debt. \|
68	\| "The registry will reject incompatible schemas anyway." \| Registry rejection at deploy time is too late. Testing in CI catches issues before code is merged and before release pressure builds. \|
69
70	## Red Flags
71
72	- no contract tests in CI — compatibility is checked only at deploy time
73	- proposed schemas are registered directly without prior compatibility validation
74	- consumer dependency map does not exist — nobody knows who reads the events
75	- breaking changes are deployed with "we'll fix consumers later" attitude
76	- test output is not stored — no evidence trail for audits
77	- compatibility policy is set to `NONE` in production subjects
78	- contract test failures are routinely overridden without review
79	- migration plans for breaking changes have no timeline or consumer notification
80
81	## Verification
82
83	- [ ] Compatibility targets are defined per subject an

People who liked this also viewed

6 picks

Type