Schema Contracts and Output Validation at Scale

Every prompt that produces structured output — JSON, YAML, a specific markdown format, a function call signature — is implicitly making a contract with every downstream system that consumes that output. The problem is that implicit contracts are unenforceable. When the prompt drifts, the output drifts, and the downstream consumer fails in a way that looks like an application bug rather than a prompt regression.

Schema contracts make those implicit agreements explicit and machine-verifiable. A schema contract defines: the required output fields, their types, their valid ranges, and any conditional constraints (if field A is present, field B is required). The prompt references its schema contract in the library metadata. Every output from that prompt is validated against the schema before it reaches the downstream consumer. Validation failures are logged, alerted, and attributed to the specific prompt version that produced them.

// Example: Schema contract for an agent handoff payload
// Referenced in library as: schema_ref: "handoff-payload.schema.json"

import { z } from 'zod';

export const HandoffPayloadSchema = z.object({
  // Required: the receiving agent must know who is handing off
  sender_agent: z.string().min(1),

  // Required: what task is being transferred
  task_id: z.string().uuid(),
  task_type: z.enum(['research', 'draft', 'review', 'escalate']),

  // Required: the work product being handed off
  payload: z.object({
    summary: z.string().max(500),
    artifacts: z.array(z.string().url()).optional(),
    context_tokens_used: z.number().int().nonneg(),
  }),

  // Required: routing metadata
  recipient_agent: z.string().min(1),
  priority: z.enum(['high', 'normal', 'low']).default('normal'),

  // Conditional: if priority is 'high', escalation_reason is required
  escalation_reason: z.string().optional(),
}).refine(
  (data) => data.priority !== 'high' || !!data.escalation_reason,
  { message: 'escalation_reason required when priority is high' }
);

export type HandoffPayload = z.infer<typeof HandoffPayloadSchema>;

// Validation wrapper — call this before routing any handoff
export function validateHandoff(raw: unknown): HandoffPayload {
  const result = HandoffPayloadSchema.safeParse(raw);
  if (!result.success) {
    // Log to prompt telemetry with the prompt version that produced the output
    throw new PromptContractViolation('handoff-payload.schema', result.error);
  }
  return result.data;
}

At scale, validation must be a middleware layer, not a one-off check. Every agent in the system routes its outputs through the validation middleware before handoff or storage. The middleware logs the prompt version, the schema version, the validation result, and the timestamp. This telemetry is your early warning system for prompt degradation — you will see the validation error rate climb before users report a problem.