Skip to content

Validation Implementation Standard

Purpose

The Validation Implementation Standard defines where validation belongs in the backend.

Validation Layers

Layer Responsibility
API boundary Request shape, required fields, type constraints, and contract validation.
Application service Use-case preconditions, authorization context, idempotency, tenant context, and workflow readiness.
Domain model Business invariants, value object meaning, aggregate consistency, and policy decisions.
Repository Persistence integrity, tenant filtering, optimistic locking, and constraint handling.
Integration adapter Provider payload validation and callback verification.

Rules

  • Validate untrusted input at the boundary.
  • Domain invariants must not rely on client-side validation.
  • Value objects carry business meaning and reject invalid values.
  • Tenant and OrganizationId context are validated before business work.
  • Idempotency validation occurs before retryable unsafe command execution.
  • Integration callbacks require source, signature, replay, and payload validation.
  • Validation errors use the standard API error envelope.

Validation Flow

flowchart LR
    Request[Request]
    Boundary[Boundary Validation]
    Context[Security and Tenant Context]
    Domain[Domain Validation]
    Persistence[Persistence Integrity]

    Request --> Boundary
    Boundary --> Context
    Context --> Domain
    Domain --> Persistence

Error Mapping

Validation failures map to stable API error codes such as VALIDATION_FAILED, TENANT_CONTEXT_REQUIRED, IDEMPOTENCY_CONFLICT, or domain-specific business rule codes.