docs: Prisma Next contract authoring (data contract, PSL, TS builder, artifacts) by tensordreams · Pull Request #8024 · prisma/web

tensordreams · 2026-07-07T10:12:21Z

Overview

Adds the Contract authoring section to the Prisma Next docs under /docs/next/contract-authoring, per the ticket's page plan: the data contract concept, PSL authoring, the TypeScript schema builder, the contract artifact, and capabilities.

Linear: DR-8680

Pages

Page	URL	Covers
The data contract	`/next/contract-authoring/the-data-contract`	The core idea, the contract-vs-schema wording note, the three jobs (type-checking, migrations, verification), how the contract is produced, choosing an authoring mode
PSL syntax	`/next/contract-authoring/psl-syntax`	`contract.prisma`: models, named `types`, enums with `@@type`, value objects, relations, `@@discriminator`/`@@base` inheritance, extension types; PostgreSQL/MongoDB tabs where syntax differs (config, full example, ID mapping)
TypeScript schema builder	`/next/contract-authoring/typescript-schema-builder`	`defineContract`: composed helpers, fields, enums, relations, storage mapping, purity rules, when to choose TS over PSL; PostgreSQL/MongoDB tabs
The contract artifact	`/next/contract-authoring/the-contract-artifact`	`contract.json` anatomy, `contract.d.ts`, deterministic emission, the hashes, runtime consumption, version control
Capabilities	`/next/contract-authoring/capabilities`	Where capability keys come from (derived from target/adapter/extension packs at emit), what they gate, real keys and error messages

Also: sidebar group under "Prisma Next" in Getting Started, a card on the Prisma Next overview page, and the five temporary redirects from the ticket (permanent: false in apps/docs/vercel.json).

Accuracy notes (deviations from the ticket, verified against product source)

Capabilities behave differently than the ticket assumes. The ticket describes "a clear error at connect time"; in the current code there is no connect-time negotiation and no E_CAPABILITY_* codes (those exist only in internal architecture docs). The real gates are (1) contract-build diagnostics (e.g. scalar lists on SQLite) and (2) query-build-time errors (distinctOn() requires capability postgres.distinctOn). The page documents the implemented behavior; capability keys are copied from the adapter/pack descriptor metadata.
profileHash currently covers target/family only (the SQL authoring path hashes an empty capability subset), so the artifact page does not claim capability changes move it.
Excluded features that appear in architecture ADRs but are not implemented: @hint(was:), the contract ESLint plugin, the authoring: config key.
All examples verified against prisma-next (examples/prisma-next-demo, examples/mongo-demo, authoring side-by-side suite). MongoDB TS examples use the @prisma-next/mongo/contract-builder facade.

Not done here (flagged per ticket)

/docs/orm/prisma-schema/overview/generators left in place (no clean equivalent; ticket suggests possibly pointing to CLI contract emit later).
Links to the Data modeling (DR-8679) and Reference (DR-8686) sections are pending; those sections don't exist in the repo yet, so links would fail the link linter. To be added when those tickets land.
The redirects shadow the live Prisma 7 schema pages once deployed; sequencing belongs to the DR-8687 cutover.

Verification

pnpm lint:links: 0 errors (594 files); pnpm audit:redirects passes with the 5 new entries
All five routes render on the local dev server (HTTP 200, correct titles, tabs and sidebar group present)

Summary by CodeRabbit

Documentation
- Added a new “Contract authoring” documentation section with new guides for the data contract, PSL syntax, TypeScript schema builders, the contract artifact outputs, and contract capabilities.
- Expanded coverage of deterministic contract emission, capability enforcement during contract/build, and database verification via stored hashes.
- Updated the docs navigation and “Next steps” links to surface the new guides.
Chores
- Updated the documentation spellcheck word list to improve authoring lint accuracy.

Add a Data contract group under orm/next with four pages: - The data contract: concept overview, authoring modes, artifacts - Author in PSL: schema syntax incl. named types, enums, value objects, relations, inheritance, and extension types - Author in TypeScript: the defineContract builder API, fields, relations, storage mapping, and purity rules - The emitted artifacts: contract.json/contract.d.ts anatomy, deterministic emission, and the content hashes Also link the new section from the Prisma Next overview cards. All examples are taken from or verified against the prisma-next repository (examples/prisma-next-demo and the authoring packages). Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

vercel · 2026-07-07T10:12:29Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
blog	Ready	Preview, Comment	Jul 7, 2026 3:46pm
docs	Ready	Preview, Comment	Jul 7, 2026 3:46pm
eclipse	Ready	Preview, Comment	Jul 7, 2026 3:46pm
site	Ready	Preview, Comment	Jul 7, 2026 3:46pm

coderabbitai · 2026-07-07T10:12:30Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 7d0ec9d6-5dd8-4e10-842c-6e9ba28399fa

📥 Commits

Reviewing files that changed from the base of the PR and between b8690d5 and 3d482db.

📒 Files selected for processing (3)

apps/docs/content/docs/orm/next/contract-authoring/psl-syntax.mdx
apps/docs/content/docs/orm/next/contract-authoring/the-data-contract.mdx
apps/docs/content/docs/orm/next/contract-authoring/typescript-schema-builder.mdx

✅ Files skipped from review due to trivial changes (3)

apps/docs/content/docs/orm/next/contract-authoring/the-data-contract.mdx
apps/docs/content/docs/orm/next/contract-authoring/psl-syntax.mdx
apps/docs/content/docs/orm/next/contract-authoring/typescript-schema-builder.mdx

Walkthrough

This PR adds a new “Contract authoring” docs section for Prisma Next, covering the data contract, PSL and TypeScript authoring, emitted artifacts, capabilities, and related navigation/support updates.

Changes

Contract authoring documentation

Layer / File(s)	Summary
Data contract concept and nav `apps/docs/content/docs/orm/next/contract-authoring/the-data-contract.mdx`, `apps/docs/content/docs/orm/next/contract-authoring/meta.json`, `apps/docs/content/docs/orm/next/meta.json`, `apps/docs/content/docs/orm/next/index.mdx`	Adds the data contract overview page and inserts the new contract-authoring section into docs navigation and the next-steps card list.
PSL authoring documentation `apps/docs/content/docs/orm/next/contract-authoring/psl-syntax.mdx`	Adds the PSL authoring page with schema configuration, examples, modeling syntax, inheritance, extension types, inference, and next-step links.
TypeScript authoring documentation `apps/docs/content/docs/orm/next/contract-authoring/typescript-schema-builder.mdx`	Adds the TypeScript contract-builder page with config wiring, builder APIs, extension handling, purity guidance, and next-step links.
Artifact and capabilities docs `apps/docs/content/docs/orm/next/contract-authoring/the-contract-artifact.mdx`, `apps/docs/content/docs/orm/next/contract-authoring/capabilities.mdx`, `apps/docs/next.config.mjs`, `apps/docs/cspell.json`	Adds the emitted artifact page, the capabilities page, and supporting redirect and spell-check dictionary updates.

Estimated code review effort: 2 (Simple) | ~12 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main docs expansion for Prisma Next contract authoring and its core pages.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

github-actions · 2026-07-07T10:13:26Z

🍈 Lychee Link Check Report

68 links: ✅ 11 OK | 🚫 0 errors | 🔀 1 redirects | 👻 56 excluded

✅ All links are working!

Full Statistics Table

Status	Count
✅ Successful	11
🔀 Redirected	1
👻 Excluded	56
🚫 Errors	0
⛔ Unsupported	0
⏳ Timeouts	0
❓ Unknown	0

argos-ci · 2026-07-07T10:15:43Z

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	✅ No changes detected	-	Jul 7, 2026, 3:53 PM

Restructure the section from orm/next/contract to the ticket's URLs under /next/contract-authoring and complete the required page set: - Move and rename the four pages to the-data-contract, psl-syntax, typescript-schema-builder, and the-contract-artifact - Add the fifth page, capabilities, documenting the implemented behavior: capabilities are derived from target/adapter/extension pack declarations at emit time, gate contract build (e.g. scalar lists on SQLite) and query building (assertCapability errors), and are not probed from the live database - Add the contract-vs-schema terminology note and the three-jobs framing to the first page - Add PostgreSQL/MongoDB tabs where authoring differs (config, full examples, ID mapping), with MongoDB examples verified against prisma-next (mongo-demo, authoring side-by-side suite) - Correct the profileHash row on the artifact page: per current code it covers target/family, not the capability subset - Add the five temporary redirects from Prisma 7 schema URLs listed in the ticket (permanent: false) - Wire the section into the Getting Started sidebar and revert the orm/next nav entries from the previous layout Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

…t-psl-ts-builder

… section Per review: - The five pages move from the getting-started tree to the ORM Next version tree: content/docs/orm/next/contract-authoring, served at /orm/next/contract-authoring/*, registered as a Contract Authoring section between Data Modeling and Fundamentals. The getting-started meta change is reverted. - The vercel.json redirects are reverted and parked, commented out, in the shared "Prisma Next URL cutover (DR-8687)" block in next.config.mjs with /orm/next destinations. They ship when the docs go GA, not now. - Cross-links into the merged sections: data modeling and Fundamentals from the data-contract page, relational/MongoDB modeling from the PSL relations syntax, Using extensions from capabilities. All internal links updated to the new paths (markdown and card hrefs). - Every page ends with the standard "Prompt your coding agent" section pointing at the Prisma Next skills, with prompts scoped to the page (prisma-next-contract). - Per-page Early Access notes removed for consistency with the other orm/next sections (the tree carries the badge); cspell terms added. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

… teaches Live validation confirmed the page's enum syntax (member values compile and the applied column carries the documented CHECK constraint) and both TypeScript builder examples (the full PostgreSQL contract with the pgvector pack emits and initializes against a live Prisma Postgres database; the MongoDB contract emits). The agent prompt that referenced namespaces, which this page does not teach, now asks for a composite unique constraint instead. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

ankur-arch · 2026-07-07T14:58:22Z

Pushed the restructure and a live-validation pass.

174cea9: the five pages move to content/docs/orm/next/contract-authoring (served at /orm/next/contract-authoring/*, registered between Data Modeling and Fundamentals), all internal links and card hrefs updated. The vercel.json redirects are reverted and parked, commented out, in the shared "Prisma Next URL cutover (DR-8687)" block; they ship at GA, not now. Cross-links into the merged sections (data modeling, Fundamentals, Using extensions), the standard "Prompt your coding agent" ending on every page, per-page Early Access notes dropped for consistency with the other orm/next sections.

517526c + validation: every substantive claim on these pages was exercised against live databases:

The enum syntax compiles as written (@@type plus Member = "value"), and the applied column carries the documented CHECK constraint, verified in the live database: (priority = ANY (ARRAY['low', 'high', 'urgent'])).
The full PostgreSQL TypeScript builder example, pgvector pack included, emits and initializes against a live Prisma Postgres database, and a cosineDistance query returns distances; the MongoDB builder example emits.
The artifact claims hold: emitting twice produces byte-identical contract.json, and db sign/db verify behave as described.
One prompt referenced namespaces, which this page doesn't teach; it now asks for something the page covers.

Validation on the branch: types clean, links 0 errors, cspell clean. Merge-ready once reviewed.

@Map

Style and coherence pass across the Prisma Next tree: - The data contract page opens plainly: what the contract is, a blog example, then the package-lock analogy, instead of a definition paragraph doing three jobs at once. Capabilities opens with the problem (databases differ) before the mechanism. The artifact page gets a one-sentence lead before its reference table. - psl-syntax now uses the same framing as the merged data modeling section: "Base models and variants" instead of "Model inheritance", the variant prose covers both storage layouts (with and without @@Map) and links the page that teaches choosing between them, and value objects link the embed-or-reference decision on MongoDB. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

ankur-arch · 2026-07-07T15:16:56Z

Style and coherence pass (b8690d5), reviewed as a reader navigating the whole Prisma Next tree. Openings now teach before they define: the data contract page starts with what the file is and a blog example before the package-lock analogy; capabilities starts with the problem (databases differ) before the mechanism; the artifact page gets a one-sentence lead before its reference table. Cross-section consistency: psl-syntax now uses the merged data modeling section's framing (Base models and variants, not Model inheritance), its variant prose covers both storage layouts and links the page that teaches choosing between them, and value objects link the embed-or-reference decision. Validation on the branch stays green: types, links, cspell.

- Lead the data contract page with a tiny PSL example and frame PSL as the preferred authoring surface with the TypeScript builder as an escape hatch for composed or programmatically assembled schemas - Drop the editor-type-checking criterion from the TS-vs-PSL comparison; PSL gets the same real-time feedback from the language server, so it is not a differentiator - Fix wording: contract source, not schema source - Move the complete PSL example above the config section so the syntax page opens with schema code Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

vercel Bot deployed to Preview – eclipse July 7, 2026 10:30 View deployment

vercel Bot deployed to Preview – blog July 7, 2026 10:30 View deployment

vercel Bot deployed to Preview – site July 7, 2026 10:30 View deployment

vercel Bot deployed to Preview – docs July 7, 2026 10:31 View deployment

aqrln reviewed Jul 7, 2026

View reviewed changes

Comment thread apps/docs/content/docs/orm/next/contract-authoring/psl-syntax.mdx

Merge branch 'main' into dr-8680-docs-contract-authoring-data-contrac…

8f358e7

…t-psl-ts-builder

vercel Bot deployed to Preview – blog July 7, 2026 14:13 View deployment

vercel Bot deployed to Preview – eclipse July 7, 2026 14:13 View deployment

vercel Bot deployed to Preview – site July 7, 2026 14:14 View deployment

vercel Bot deployed to Preview – docs July 7, 2026 14:15 View deployment

aqrln reviewed Jul 7, 2026

View reviewed changes

Comment thread apps/docs/content/docs/orm/next/contract-authoring/psl-syntax.mdx Outdated

aqrln reviewed Jul 7, 2026

View reviewed changes

Comment thread apps/docs/content/docs/orm/next/contract-authoring/the-data-contract.mdx Outdated

aqrln reviewed Jul 7, 2026

View reviewed changes

Comment thread apps/docs/content/docs/orm/next/contract-authoring/the-data-contract.mdx

aqrln reviewed Jul 7, 2026

View reviewed changes

Comment thread apps/docs/content/docs/(index)/next/contract-authoring/the-data-contract.mdx Outdated

aqrln reviewed Jul 7, 2026

View reviewed changes

Comment thread apps/docs/content/docs/orm/next/contract-authoring/typescript-schema-builder.mdx Outdated

aqrln marked this pull request as ready for review July 7, 2026 14:40

vercel Bot deployed to Preview – blog July 7, 2026 14:43 View deployment

vercel Bot deployed to Preview – eclipse July 7, 2026 14:43 View deployment

vercel Bot deployed to Preview – site July 7, 2026 14:44 View deployment

vercel Bot deployed to Preview – docs July 7, 2026 14:45 View deployment

vercel Bot deployed to Preview – eclipse July 7, 2026 14:59 View deployment

vercel Bot deployed to Preview – blog July 7, 2026 14:59 View deployment

vercel Bot deployed to Preview – site July 7, 2026 14:59 View deployment

vercel Bot deployed to Preview – docs July 7, 2026 15:00 View deployment

ankur-arch mentioned this pull request Jul 7, 2026

docs: add Prisma Next Migrations section #8025

Merged

vercel Bot deployed to Preview – blog July 7, 2026 15:45 View deployment

vercel Bot deployed to Preview – eclipse July 7, 2026 15:45 View deployment

vercel Bot deployed to Preview – site July 7, 2026 15:45 View deployment

vercel Bot deployed to Preview – docs July 7, 2026 15:46 View deployment

nurul3101 approved these changes Jul 8, 2026

View reviewed changes

nurul3101 merged commit 04449e7 into main Jul 8, 2026
21 checks passed

nurul3101 deleted the dr-8680-docs-contract-authoring-data-contract-psl-ts-builder branch July 8, 2026 10:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: Prisma Next contract authoring (data contract, PSL, TS builder, artifacts)#8024

docs: Prisma Next contract authoring (data contract, PSL, TS builder, artifacts)#8024
nurul3101 merged 7 commits into
mainfrom
dr-8680-docs-contract-authoring-data-contract-psl-ts-builder

tensordreams commented Jul 7, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

vercel Bot commented Jul 7, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 7, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 7, 2026 •

edited

Loading

Uh oh!

argos-ci Bot commented Jul 7, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ankur-arch commented Jul 7, 2026

Uh oh!

ankur-arch commented Jul 7, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

tensordreams commented Jul 7, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Pages

Accuracy notes (deviations from the ticket, verified against product source)

Not done here (flagged per ticket)

Verification

Summary by CodeRabbit

Uh oh!

vercel Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Uh oh!

github-actions Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🍈 Lychee Link Check Report

✅ All links are working!

Uh oh!

argos-ci Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ankur-arch commented Jul 7, 2026

Uh oh!

ankur-arch commented Jul 7, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

tensordreams commented Jul 7, 2026 •

edited by coderabbitai Bot

Loading

vercel Bot commented Jul 7, 2026 •

edited

Loading

coderabbitai Bot commented Jul 7, 2026 •

edited

Loading

github-actions Bot commented Jul 7, 2026 •

edited

Loading

argos-ci Bot commented Jul 7, 2026 •

edited

Loading