schema-contract-governance

To choose between Zod and JSON Schema for data contracts, evaluate whether you need TypeScript-native runtime validation or framework-agnostic schema definitions. This governance skill guides that selection to maintain consistency.

You need formal schema definitions instead of JSDoc when introducing new APIs or shared data structures that require runtime validation and strict maintainability. JSDoc suffices only for simple, non-validated type hints.

The best way to enforce consistent type definitions is applying a contract layering strategy using .d.ts files, Zod, or JSON Schema based on data requirements. This ensures appropriate abstraction levels and maintainability.

Yes, you can use this schema governance strategy for shared types and report schemas. It addresses scenarios involving data contracts for APIs, reports, and runtime validation to ensure clarity and consistency.

Your repository has inconsistent data contracts because it lacks a governed layering strategy for selecting between JSDoc, .d.ts files, JSON Schema, and Zod. Enforcing a standard approach prevents these inconsistencies.