Integration Contract Validation Checklist

Version: 1.0.0
Last Updated: 2026-01-15
Constitution Reference: Section 1.3 (Integration Patterns)

---

​

Overview

Use this checklist when adding or modifying integration contracts to ensure completeness and consistency. This serves as a quality gate before merging integration documentation. Related Documents:

• EVENT_CONTRACTS.md - Event-based integrations
• API_CONTRACTS.md - API contracts
• PLATFORM_INTEGRATION_LAYERS.md - Platform integration layers
• CROSS_CORE_INTEGRATIONS.md - Integration matrix

---

​

Event Contract Validation

Complete this checklist when adding a new event to EVENT_CONTRACTS.md:

​

Event Definition

• Event name follows {core}_{entity}_{action} convention (canonical format, snake_case, past tense)
• Channel specified (domain_events, automation_trigger, fa_events, etc.)
• Publisher identified with core and feature ID
• Subscribers listed with their actions
• Status indicator accurate (✅ Implemented / 📝 Planned / 🟡 In Progress)
• Spec reference linked to specification document

​

Payload Schema

• event_type field included (string, matches event name)
• organization_id field included (uuid, required for tenant isolation)
• timestamp field included (timestamptz)
• site_id field included if site-scoped
• user_id field included if user-initiated action
• correlation_id documented if event chaining is possible
• All fields have TypeScript types and descriptions
• No PII/PHI in payload (use IDs only)

​

Implementation

• Trigger conditions documented (when event fires)
• SQL trigger code provided with SECURITY DEFINER
• Consumer actions listed with status
• Testing requirements defined

​

Backward Compatibility

• Breaking changes documented (if any)
• Migration guide provided (if replacing existing event)
• Deprecation date noted (if applicable)

---

​

API Contract Validation

Complete this checklist when adding a new API to API_CONTRACTS.md:

​

API Definition

• Endpoint fully specified (/api/v1/{core}/{resource})
• HTTP method documented (GET, POST, PUT, DELETE, PATCH)
• Provider identified with core and feature ID
• Consumer(s) listed
• Status indicator accurate
• Spec reference linked

​

Request Documentation

• Path parameters documented with types
• Query parameters documented with types, defaults, descriptions
• Request body schema provided as TypeScript interface
• Required vs optional fields clearly distinguished
• Content-Type specified

​

Response Documentation

• Success response schema provided (200/201)
• Error response schema follows standard format
• All HTTP status codes documented
• Error codes listed with descriptions and resolutions

​

Security & Operations

• Authentication requirements documented (JWT)
• Tenant context enforcement described
• Rate limiting values and headers documented
• PII/PHI logging guidelines included (what can/cannot be logged)
• Permission requirements documented (if applicable)

​

Quality & Performance

• Usage example provided (working TypeScript code)
• Performance SLA documented (p50, p95, p99)
• Timeout recommendation included
• Retry semantics documented (safe to retry?)
• Idempotency behavior documented (for write operations)
• Caching strategy documented (if applicable)

​

Testing

• Testing requirements listed
• Error scenarios covered

---

​

Platform Integration Layer Validation

Complete this checklist when adding a new layer to PLATFORM_INTEGRATION_LAYERS.md:

​

Layer Definition

• Layer name and location documented (/src/platform/{layer}/)
• Purpose clearly described (1-2 sentences)
• Consumer cores listed
• Status indicator accurate
• Version noted

​

Public API

• All exports documented (components, hooks, utilities)
• TypeScript interfaces provided for public types
• Import path documented (@/platform/{layer})

​

Usage

• Usage example provided (working code)
• Common patterns documented
• Anti-patterns listed (what NOT to do)

​

Dependencies

• Internal dependencies listed (other platform layers)
• External dependencies documented (npm packages)
• Core dependencies noted (if any)

---

​

Cross-Core Integration Validation

Complete this checklist when adding an integration to CROSS_CORE_INTEGRATIONS.md:

​

Matrix Entry

• Row added to integration matrix
• Publisher/Provider correctly identified
• Consumer correctly identified
• Integration type specified (Platform Layer / Event / API)
• Status accurate (✅ / 📝 / 🟡)
• Documentation link provided

​

Documentation

• Contract documented in appropriate file:
  • Event → EVENT_CONTRACTS.md
  • API → API_CONTRACTS.md
  • Platform Layer → PLATFORM_INTEGRATION_LAYERS.md
• Both publisher and consumer perspectives documented
• Data flow described

---

​

Pre-Merge Checklist

Before merging integration documentation changes, verify:

​

Documentation Completeness

• All new integrations added to CROSS_CORE_INTEGRATIONS.md matrix
• Contract documented in appropriate contracts file
• Related spec references updated
• README.md overview updated (if new pattern introduced)

​

Cross-Reference Validation

• Links between documents work correctly
• Spec references are valid paths
• Version numbers consistent across documents

​

Review Requirements

• Self-review completed using this checklist
• Architecture review requested (for new patterns)
• Security review requested (for sensitive data integrations)

---

​

Quick Reference: Integration Pattern Selection

Use this guide to choose the right integration pattern:

---

​

Common Validation Failures

​

Event Contracts

​

API Contracts

​

Platform Layers

---

​

Versioning

---

​

See Also

• specs/_templates/INTEGRATION_CONTRACT_TEMPLATE.md - Event, API, and Database Function contract templates (combined)
• docs/architecture/patterns/INTEGRATION_EXAMPLES.md - Code examples
• constitution.md §1.3 - Integration patterns

---

Document Owner: Platform Foundation
Review Cadence: Quarterly
Next Review: 2026-04-15