Data Contracts and System Boundaries

{
  "user_id": "string (required)",
  "email": "string (required, email format)",
  "age": "number (optional, >= 0)",
  "created_at": "timestamp (required)"
}

{
  "user_id": "UUID, uniquely identifies this user",
  "email": "valid email address, unique across all users",
  "age": "user's age in years, must be >= 0, null if unknown",
  "created_at": "ISO 8601 timestamp, immutable, set when user created"
}

User:
  required:
    - id: unique identifier
    - email: contact email
    - name: user name
  optional:
    - phone: contact phone number (null if not provided)
    - timezone: user timezone (defaults to UTC if not provided)

Order:
  status: "enum: pending, processing, shipped, delivered, cancelled"
  priority: "enum: low, medium, high"
  quantity: "integer, >= 1, <= 10000"

User:
  id: "UUID (format: 8-4-4-4-12 hex digits)"
  created_at: "ISO 8601 timestamp with timezone (e.g., 2026-03-05T14:30:00Z)"
  revenue: "decimal number with exactly 2 decimal places (e.g., 100.00)"

# Order Status Semantics

- **pending**: Order placed, payment not yet processed. Can transition to: processing, cancelled
- **processing**: Payment processed, preparing to ship. Can transition to: shipped, cancelled
- **shipped**: Order dispatched. Can transition to: delivered
- **delivered**: Recipient confirmed receipt. Terminal state.
- **cancelled**: Order cancelled by user or system. Terminal state.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "user_id": {
      "type": "string",
      "format": "uuid"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 0
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": ["user_id", "email", "created_at"]
}

{
  "type": "record",
  "name": "User",
  "fields": [
    {"name": "user_id", "type": "string"},
    {"name": "email", "type": "string"},
    {"name": "age", "type": ["null", "int"], "default": null},
    {"name": "created_at", "type": "long"}
  ]
}

message User {
  string user_id = 1;
  string email = 2;
  optional int32 age = 3;
  int64 created_at_millis = 4;
}

// Consumer's expectation (team-b/test/pact.test.js)
const PactProvider = require('@pact-foundation/pact');

describe('User Service contract', () => {
  it('returns a user by ID', async () => {
    await pactProvider
      .addInteraction({
        state: 'user 123 exists',
        uponReceiving: 'a request for user 123',
        withRequest: {
          method: 'GET',
          path: '/users/123'
        },
        willRespondWith: {
          status: 200,
          body: {
            id: '123',
            email: 'alice@example.com',
            name: 'Alice'
          }
        }
      });

    const user = await userService.getUser('123');
    expect(user.id).toBe('123');
  });
});

const Ajv = require('ajv');
const ajv = new Ajv();
const schema = require('./schemas/user.json');
const validate = ajv.compile(schema);

describe('User data contract', () => {
  it('validates correct user data', () => {
    const user = {
      user_id: '550e8400-e29b-41d4-a716-446655440000',
      email: 'alice@example.com',
      age: 30,
      created_at: '2026-03-05T14:30:00Z'
    };
    expect(validate(user)).toBe(true);
  });

  it('rejects invalid email', () => {
    const user = {
      user_id: '550e8400-e29b-41d4-a716-446655440000',
      email: 'not-an-email',
      created_at: '2026-03-05T14:30:00Z'
    };
    expect(validate(user)).toBe(false);
  });
});

describe('Order data semantics', () => {
  it('validates valid status transition', () => {
    const order = {
      id: '123',
      status: 'processing',
      previous_status: 'pending'
    };
    expect(isValidStatusTransition(order)).toBe(true);
  });

  it('rejects invalid status transition', () => {
    const order = {
      id: '123',
      status: 'pending',
      previous_status: 'delivered'
    };
    expect(isValidStatusTransition(order)).toBe(false);
  });
});

OrderCreated:
  fields:
    - order_id: UUID
    - customer_id: UUID
    - total_amount: decimal with 2 places
    - created_at: ISO 8601 timestamp

GET /api/orders/{id}:
  response:
    - order_id: UUID
    - status: enum (pending, processing, shipped, delivered)
    - items: array of items
    - total: decimal with 2 places

-- System B can read this view
CREATE VIEW orders_for_reporting AS
SELECT
  order_id,
  customer_id,
  total_amount,
  created_at,
  completed_at
FROM orders;

# Before
User:
  required: [id, email]

# After
User:
  required: [id, email]
  optional: [phone, timezone]  # new field