patterns-shared-schemas.md

---

title: Zod-схемы и граница контракта между qadam-core и qadam-web impact: HIGH impactDescription: Не даёт смешивать internal validation schemas и внешний web-контракт после split репозиториев tags: patterns, zod, validation, shared, openapi, repo-boundaries

Паспорт документа

• Статус документа: living standard
• Актуально на: 28 марта 2026 года
• Владелец: backend/platform-команда
• Пересмотр: при изменении инженерной практики, CI/CD, архитектурных правил или локального workflow
• Область применения: внутренние rule/reference-card документы для инженерной команды
• Связанные документы:
  • Индекс Agents
  • Команды разработки
  • Инженерные принципы

Zod-схемы и граница контракта

Impact: HIGH

После разделения репозиториев правило изменилось:

• внутри qadam-core Zod-схемы в packages/shared остаются каноническим слоем input validation;
• qadam-web больше не должен импортировать @repo/shared как рабочую зависимость для transport layer;
• внешний web-контракт теперь проходит через OpenAPI artifact и generated types.

Где живут схемы

В qadam-core:

packages/shared/src/
  schemas/
  constants/

Именно эти схемы использует backend для:

• валидации входных данных;
• типизации DTO;
• OpenAPI generation и contract alignment.

Что использует frontend

В qadam-web источником истины по transport layer являются:

• openapi/openapi.json
• apps/web/src/shared/api/generated/openapi.d.ts

Локальные form-level схемы во frontend допустимы только для UI/UX-валидации, но они не должны подменять backend-контракт.

Правила

• Backend input validation описывается в qadam-core/packages/shared.
• OpenAPI artifact экспортируется из qadam-core.
• qadam-web получает contract types через codegen, а не через импорт backend-исходников.
• Нельзя возвращать frontend к прямому импорту @repo/shared ради “удобства”.
• Если схема изменилась и затронула web, change package обязан обновить OpenAPI artifact и mirror в qadam-web.