Pasta contracts e JSON Schema

Nesta aula você vai estruturar os contratos do monorepo e definir o schema oficial do evento order.created.

Estrutura de diretórios

contracts/
  events/
    order.created/
      v1/
        schema.json
        examples/
          valid.json
          invalid-missing-customerId.json

Passo 1 - Defina o schema base

Arquivo: contracts/events/order.created/v1/schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "order.created.v1",
  "type": "object",
  "required": ["eventType", "eventVersion", "orderId", "customerId", "items"],
  "properties": {
    "eventType": { "const": "order.created" },
    "eventVersion": { "const": "v1" },
    "orderId": { "type": "string", "minLength": 1 },
    "customerId": { "type": "string", "minLength": 1 },
    "items": { "type": "array", "minItems": 1 }
  },
  "additionalProperties": false
}

Passo 2 - Crie exemplos válidos/inválidos

• contracts/events/order.created/v1/examples/valid.json
• contracts/events/order.created/v1/examples/invalid-missing-customerId.json

Esses exemplos serão usados por testes automatizados nas próximas aulas.

Passo 3 - Documente ownership do contrato

Crie contracts/events/README.md com:

• Time dono do evento (ex.: squad Order).
• Consumidores impactados (Payment, Analytics).
• Política de depreciação.

Passo 4 - Validação rápida local

Use ajv-cli no diretório do monorepo:

npm i -D ajv-cli
npx ajv validate \
  -s contracts/events/order.created/v1/schema.json \
  -d contracts/events/order.created/v1/examples/valid.json

Teste inválido:

npx ajv validate \
  -s contracts/events/order.created/v1/schema.json \
  -d contracts/events/order.created/v1/examples/invalid-missing-customerId.json

Resultado esperado

• Primeiro comando retorna sucesso.
• Segundo comando falha informando ausência de customerId.

Resumo

Você estruturou contratos versionados e criou JSON Schema executável, transformando o diretório contracts/events na fonte de verdade para integração assíncrona.