docs(orm/next): data modeling guides

[SevInf]

What

Adds a Data modeling section under the Prisma Next docs (/orm/next/data-modeling) with three pages:

• Overview — what a model is, primary keys (natural vs. surrogate + how to choose the type), scalar fields (how to pick a data type), and what a relation is.
• Relational databases — one-to-one, one-to-many, many-to-many (implicit + explicit), and polymorphic relations, plus how to pick which side owns the foreign key.
• MongoDB — documents/ObjectId, the embed-vs-reference decision, references, and polymorphic collections.

Registers the section in the Next nav (orm/next/meta.json).

Notes for reviewers

• Draft. Conceptual guides, not a PSL syntax reference — snippets illustrate the concepts.

• ⚠️ In-flight syntax. Relation snippets use the directional @relation(from:, to:) vocabulary and implicit many-to-many from the unmerged PSL relation-syntax stack:

  • TML-2940: from/to FK relation syntax — clean break, reject legacy fields/references prisma-next#872
  • TML-2941: through: explicit many-to-many junction authoring in PSL prisma-next#873
  • TML-2942: disambiguate relations by pointing, retire @relation(name:) prisma-next#874
  • TML-2943: implicit many-to-many via a synthesised model-less junction prisma-next#875
  • TML-2944: arrow-path through: for relation-field-less junctions prisma-next#876

  These need a re-check against source before publishing.

• MongoDB many-to-many is intentionally omitted for now.

• Docs forward-reference a "relations reference" and "MongoDB query material" that don't exist yet — those pointers are intentional placeholders.

• All PSL was cross-checked against the prisma/prisma-next source rather than prior Prisma syntax.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added a new “Data modeling” section for Prisma Next, covering core schema concepts, SQL and MongoDB modeling, and when to use different relation patterns.
  • Published dedicated guides for relational databases and MongoDB, with examples, decision guidance, and next-step links.
  • Expanded the docs-writing guide with clearer teaching and structure rules for step-by-step content.
  • Updated navigation and redirects so the new content is easier to find from existing ORM docs.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
blog	Ready	Preview, Comment	Jul 7, 2026 10:59am
docs	Ready	Preview, Comment	Jul 7, 2026 10:59am
eclipse	Ready	Preview, Comment	Jul 7, 2026 10:59am
site	Ready	Preview, Comment	Jul 7, 2026 10:59am

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 83b11a8f-e1ef-489f-b2ef-d0efd1e166e6

📥 Commits

Reviewing files that changed from the base of the PR and between d53997d and df1ad9b.

📒 Files selected for processing (7)

• .claude/skills/docs-writer/SKILL.md
• apps/docs/content/docs/orm/next/data-modeling/index.mdx
• apps/docs/content/docs/orm/next/data-modeling/meta.json
• apps/docs/content/docs/orm/next/data-modeling/mongodb.mdx
• apps/docs/content/docs/orm/next/data-modeling/relational-databases.mdx
• apps/docs/content/docs/orm/next/meta.json
• apps/docs/next.config.mjs

---

Walkthrough

This PR adds Prisma Next data modeling docs for overview, relational, and MongoDB modeling, wires them into navigation metadata, adds commented redirect placeholders, and updates the docs-writer skill guide with plain-language teaching guidance.

Changes

Data modeling documentation

Layer / File(s)	Summary
Docs-writer skill guidance update .claude/skills/docs-writer/SKILL.md	Adds a "Teach in plain language" section with rules on concept ordering, paragraph decomposition, jargon placement, and hands-on guide structure.
Data modeling overview page apps/docs/content/docs/orm/next/data-modeling/index.mdx, apps/docs/content/docs/orm/next/data-modeling/meta.json	New page covering models, primary keys, scalar fields, relations, agent prompts, and next steps; meta.json lists index, relational-databases, and mongodb pages.
Relational databases guide apps/docs/content/docs/orm/next/data-modeling/relational-databases.mdx	New page documenting one-to-many, one-to-one, many-to-many, and polymorphic relations with examples, agent prompts, and next steps.
MongoDB modeling guide apps/docs/content/docs/orm/next/data-modeling/mongodb.mdx	New page documenting collection/document mapping, embed vs reference trade-offs, embedded documents, referenced relations, polymorphic collections, agent prompts, and next steps.
Navigation and redirects apps/docs/content/docs/orm/next/meta.json, apps/docs/next.config.mjs	Adds a "Data Modeling" entry to ORM next navigation and commented future redirect mappings for the new pages.

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

Possibly related PRs

• prisma/web#7981: Both PRs modify .claude/skills/docs-writer/SKILL.md, adjusting the docs-writer guidance text.

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions]

🍈 Lychee Link Check Report

18 links: ✅ 0 OK | 🚫 0 errors | 🔀 0 redirects | 👻 18 excluded

✅ All links are working!

---

Full Statistics Table

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

[argos-ci]

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

Build	Status	Details	Updated (UTC)
default (Inspect)	✅ No changes detected	1 ignored	Jul 7, 2026, 11:01 AM

[ankur-arch]

Pushed a revision (b436d39) addressing the review feedback, with every schema snippet emit-tested against @prisma-next 0.14.0 before landing in the pages.

Accuracy fixes (tested):

Construct in the previous draft	0.14.0	Change
@relation(from: [...], to: [...])	Rejected: unsupported argument "from" (main only accepts fields/references/map/onDelete/onUpdate too)	All examples now use @relation(fields:, references:)
Implicit many-to-many (Tag[] both sides)	Rejected: "use an explicit join model for many-to-many"	Section now teaches the explicit junction model as the working pattern and names the implicit form as not supported yet
@relation(through: UserTag)	Rejected: unsupported argument	Removed; junction declared with two plain relations
Composite @@id, @@discriminator/@@base (both layouts), Mongo type blocks, uuid()	All pass	Kept

Writing and structure:

• Plain-language intros (idea first, blog example, terms last), no em dashes; the docs-writer skill now codifies this in a "Teach in plain language" section so the parallel PRs can follow it.
• Bare (1:1) / (1:n) / (m:n) were being eaten by remark-directive and rendered as (1\n). Backticked now, verified intact in the rendered HTML.
• Dense paragraphs broken into scannable subsections with code blocks: natural vs surrogate keys (Country ISO example, User/Product + @unique), surrogate type choice, data type choice, and "Which side owns the foreign key" as an assertive checklist.
• MongoDB shown with tab switchers where it differs, cross-links into the Fundamentals pages for querying each shape, "Prompt your coding agent" endings, and direct link phrasing ("To model relational data, see...").
• DR-8679 redirects parked, commented out, in next.config.mjs under the shared "Prisma Next URL cutover (DR-8687)" block per the convention in the docs-writer skill.

Validation: cspell 0 issues, types:check clean, rendered-HTML check for the directive fix. Happy to iterate on any of it.

[ankur-arch]

Live-database pass on top of the emit matrix, 2026-07-07: on a fresh Prisma Postgres database, db init applied the page's schemas and the natural-key example works as written (Country create/read by ISO code). Variant models work live with one caveat now noted on the page: variants appear as ORM roots and base queries return variant rows, but creating through a variant needs the discriminator passed explicitly on 0.14.0 (d652e12 adds that sentence). On a local MongoDB replica set, the embedded-type examples run live: creating a user with a nested address returns the document with the embedded object intact. Side note for the CLI team: switching an already-signed database to a different contract via db update -y failed mid-plan on a foreign-key drop ordering (dropTable post before its junction); fresh db init works fine.

[ankur-arch]

Pushed 291c565: the sidebar now reads Data Modeling as its own section with Overview, Relational data modeling, and MongoDB data modeling as its pages (separator + flattened folder, index retitled Overview; SEO title unchanged via metaTitle).

[ankur-arch]

Synced with main now that Fundamentals (#8011) is merged: conflicts resolved (sidebar now reads Introduction, Data Modeling, Fundamentals; the cutover comment blocks are combined), and the cross-links from these pages into the Fundamentals section now resolve against main. Link check runs 0 errors on the branch; types clean. Merge-ready.