JSON Data Contracts — Schema Governance & Contract Testing

1name: Schema Compatibility Check
2on:
3  pull_request:
4    paths: ['contracts/**/*.json', 'contracts/**/*.yaml']
5
6jobs:
7  check:
8    runs-on: ubuntu-latest
9    steps:
10      - uses: actions/checkout@v4
11        with:
12          fetch-depth: 0
13
14      - name: Check backward compatibility
15        run: |
16          # Compare modified schemas against main branch
17          for file in $(git diff --name-only origin/main -- contracts/); do
18            echo "Checking $file..."
19            npx json-schema-diff \
20              <(git show origin/main:$file) \
21              "$file" \
22              --fail-on-breaking
23          done
24
25      - name: Validate all schemas
26        run: |
27          npx ajv validate -s meta-schema.json -d 'contracts/**/*.json'

1import { PactV3 } from '@pact-foundation/pact';
2
3const provider = new PactV3({
4  consumer: 'billing-service',
5  provider: 'user-service',
6});
7
8describe('User API Contract', () => {
9  it('returns user profile for billing', async () => {
10    // Define what the consumer expects
11    await provider
12      .given('user u123 exists')
13      .uponReceiving('a request for user profile')
14      .withRequest({ method: 'GET', path: '/api/v2/users/u123' })
15      .willRespondWith({
16        status: 200,
17        headers: { 'Content-Type': 'application/json' },
18        body: {
19          user_id: 'u123',           // billing uses this field
20          email: '[email protected]', // billing uses this field
21          plan: 'pro',               // billing uses this field
22        },
23      });
24
25    await provider.executeTest(async (mockServer) => {
26      const response = await fetch(
27        `${mockServer.url}/api/v2/users/u123`
28      );
29      const user = await response.json();
30
31      // Assert the fields billing actually depends on
32      expect(user.user_id).toBeDefined();
33      expect(user.email).toBeDefined();
34      expect(user.plan).toMatch(/^(free|pro|enterprise)$/);
35    });
36  });
37});

1import { Verifier } from '@pact-foundation/pact';
2
3describe('User Service Provider Verification', () => {
4  it('satisfies all consumer contracts', async () => {
5    const verifier = new Verifier({
6      providerBaseUrl: 'http://localhost:3000',
7      pactBrokerUrl: process.env.PACT_BROKER_URL,
8      provider: 'user-service',
9      publishVerificationResult: true,
10      providerVersion: process.env.GIT_SHA,
11
12      // Set up test data for each contract state
13      stateHandlers: {
14        'user u123 exists': async () => {
15          await db.users.create({
16            user_id: 'u123',
17            email: '[email protected]',
18            plan: 'pro',
19          });
20        },
21      },
22    });
23
24    await verifier.verifyProvider();
25    // If any consumer contract is broken, this test FAILS
26    // preventing the producer from deploying
27  });
28});