docs(orm/next): add data modeling guides

Add a data modeling section under Prisma Next docs with three pages:

- Overview: models, primary keys (how to pick), scalar fields (how to
  pick a type), and relations
- Relational databases: 1:1, 1:n, m:n (implicit + explicit), and
  polymorphic relations, plus foreign-key ownership guidance
- MongoDB: documents, embed-vs-reference, references, and polymorphic
  collections

Register the section in the Next nav.

Note: relation snippets use the in-flight directional `@relation(from:, to:)`
syntax and implicit m:n from the unmerged PSL relation-syntax stack
(prisma/prisma-next #872-876); verify before publishing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: SevInf

apps/docs/content/docs/orm/next/data-modeling/index.mdx

@@ -0,0 +1,156 @@
+---
+title: Data modeling overview
+description: How to model your application domain in Prisma Next — models, primary keys, scalar fields, and relations.
+url: /orm/next/data-modeling
+metaTitle: Data modeling in Prisma Next
+metaDescription: Learn the building blocks of a Prisma Next data model — models, primary keys, scalar field types, and relations — and how they map to relational and document databases.
+badge: early-access
+---
+
+Data modeling is the step where you describe the shape of your application's data: the entities it works with, the fields each entity carries, and how those entities connect. In Prisma Next you author that description as a **schema**, and Prisma Next compiles it into a versioned [contract](/orm/next) that your code, your migrations, and your tooling all read from.
+
+This page introduces the four building blocks you use in every Prisma Next schema:
+
+- [Models](#models) — the entities of your domain
+- [Primary keys](#primary-keys) — how each record is identified
+- [Scalar fields](#scalar-fields) — the individual values a model stores
+- [Relations](#relations) — how models connect to each other
+
+The building blocks below apply to every database. Where they diverge is in how you model relations, which the database-specific guides linked at the end cover in depth.
+
+## Models
+
+A **model** describes one kind of entity in your domain: a user, an order, a blog post. Every model has a unique identity and its own lifecycle, which is what separates it from a plain bag of values. Two posts with the same title are still two different posts, and a user who changes their email address is still the same user.
+
+You declare a model with the `model` keyword and give it a set of fields:
+
+```prisma
+model User {
+  id    Int    @id @default(autoincrement())
+  email String
+  name  String?
+}
+```
+
+How a model maps to physical storage, and which models become queryable entry points, depends on the database and is covered in the database-specific guides.
+
+## Primary keys
+
+A **primary key** is the field (or fields) that uniquely identifies each record in a model. Every model needs one. You mark it with the `@id` attribute:
+
+```prisma
+model User {
+  id    Int    @id @default(autoincrement())
+  email String
+}
+```
+
+The value can be generated by the database or by Prisma Next. Common choices:
+
+- **Auto-incrementing integer** — `Int @id @default(autoincrement())`. Compact and ordered, but sequential and predictable.
+- **UUID** — `String @id @default(uuid())`. Globally unique and safe to generate on the client, at the cost of a wider key.
+- **MongoDB ObjectId** — `ObjectId @id @map("_id")`. The idiomatic MongoDB identifier, embedding a creation timestamp.
+
+A key can also span multiple fields. A **composite primary key** uses the `@@id` block attribute, for when a record is identified by a combination of values rather than a single one:
+
+```prisma
+model UserTag {
+  userId Int
+  tagId  String
+
+  @@id([userId, tagId])
+}
+```
+
+### How to pick a primary key
+
+The first decision is **natural vs. surrogate**. A natural key is an attribute that already identifies the record uniquely: a product's SKU, a book's ISBN, a country's ISO code. A surrogate key is a synthetic value with no business meaning: an auto-incrementing integer, a UUID, an ObjectId.
+
+A **natural key** is the right choice when the value is genuinely stable, unique, and externally assigned — a standardized code your application receives rather than invents. A `Country` keyed by its ISO code (`US`, `DE`), a `Currency` keyed by its ISO code (`USD`, `EUR`), or a `UsState` keyed by its two-letter abbreviation are good fits: the code is the identity, it never changes, and using it as the key means other records store a readable value (`US`) directly instead of an opaque number. Reference and lookup tables like these are where natural keys shine.
+
+A **surrogate key** is the better default for most entities you create yourself. The reason is stability: natural keys you'd be tempted to use — a user's email, a product's SKU — do change in practice, and changing a primary key is expensive because everything that already points at the old value has to be updated too. A surrogate never changes, so it stays a dependable identifier for the life of the record. Keep the natural attribute as well and enforce it with `@unique`: a `User` gets a surrogate `id` plus `email String @unique`, a `Product` gets a surrogate `id` plus `sku String @unique`. You get a stable key *and* the uniqueness guarantee.
+
+Once you've chosen a surrogate, pick its type by how the record is created and referenced:
+
+- **Auto-incrementing integer** (`Int @id @default(autoincrement())`) — the smallest and fastest key to index, and naturally ordered by insertion. Good for an internal `Order` or `Invoice` whose id never leaves your system. The trade-offs: the database assigns the value, so you don't know it until after the insert; it's sequential and therefore guessable, which leaks row counts and invites enumeration if you expose it; and separate sources can't generate ids without colliding.
+- **UUID** (`String @id @default(uuid())`) — globally unique and generated in your application before the insert, so you know the id up front and independent sources never collide. A fit for a `User` or `ApiToken` whose id appears in URLs or is created across services, where you don't want to leak counts. The cost is size (a UUID is far wider than an integer) and, for random UUIDs, worse index locality than a sequential key.
+- **MongoDB ObjectId** (`ObjectId @id @map("_id")`) — the idiomatic MongoDB key: generated without coordination, compact, and it embeds its own creation time. The default for any MongoDB model, for example a `Post` document. See the [MongoDB guide](/orm/next/data-modeling/mongodb).
+
+Use a **composite key** when the identity genuinely *is* the combination of two values. The clearest case is a model that links two others: a `UserTag` connecting a user and a tag is identified by the pair `(userId, tagId)`, and a duplicate pair would be meaningless. Avoid composite keys as the identity of ordinary entities, because everything that points at the model then has to carry all of the key's columns.
+
+## Scalar fields
+
+A **scalar field** holds a single value of a primitive type. The common scalar types are:
+
+| Type       | Stores                                    |
+| ---------- | ----------------------------------------- |
+| `String`   | Text                                      |
+| `Int`      | 32-bit integer                            |
+| `BigInt`   | 64-bit integer                            |
+| `Float`    | Floating-point number                     |
+| `Boolean`  | `true` / `false`                          |
+| `DateTime` | Timestamp                                 |
+| `Json`     | Arbitrary JSON value                      |
+| `ObjectId` | MongoDB document identifier               |
+
+This isn't the whole set. Prisma Next's type system is extensible, so more scalar types — a dedicated `Uuid`, or types contributed by extensions — are available beyond the common ones above.
+
+Two modifiers change a field's shape:
+
+- A trailing `?` makes the field **optional** (`name String?`).
+- A trailing `[]` makes it a **list** (`tags String[]`).
+
+### How to pick a data type
+
+Match the type to the **meaning** of the value, not to how it happens to look:
+
+- **An identifier is a `String`, not an `Int`, unless you do arithmetic on it.** Zip codes, phone numbers, and order references look numeric but you never add them, they can have leading zeros, and they aren't ordered numerically. Store them as `String`.
+- **Money is not a `Float`.** Floating-point types can't represent decimal amounts exactly, so sums drift by fractions of a cent. Store currency as an integer number of minor units (cents), or use a dedicated decimal type where one is available.
+- **An instant is a `DateTime`, not a `String`.** A real timestamp type gives you correct comparison, sorting, and range queries; a string gives you none of those and invites format bugs.
+- **A fixed set of values is an enum, not a free-form `String`.** When a field only ever holds one of a known set — a status, a role, a priority — an `enum` documents the allowed values and rejects anything else. (Enum authoring differs slightly by database; see the family guides.)
+
+Size a field for the data it will realistically hold, including future growth. A narrower type (`Int` over `BigInt`) documents intent and costs a little less to store, but the choice is asymmetric: widening a type later — when a counter overflows `Int`, say — is a migration, so when you're unsure, lean toward the type you won't have to change. Mark a field optional (`?`) only when "absent" is a meaningful state distinct from a sensible default; a required field with a default is often the clearer model.
+
+## Relations
+
+A **relation** is a connection between two models. Relations are the backbone of most schemas: a user *has* many orders, an order *belongs to* one user, a post *has* many tags.
+
+Two things describe any relation — its cardinality and which side stores it.
+
+### Cardinality
+
+Cardinality is how many records connect on each side. There are three shapes:
+
+- **One-to-one** — a record on each side links to at most one on the other. A user and their profile; an order and its shipment.
+- **One-to-many** — one record links to many, and each of those links back to a single one. A user and their orders; a post and its comments.
+- **Many-to-many** — records on both sides link to many. Posts and tags; students and courses.
+
+### Ownership
+
+A relation is physically stored by one model holding a link to the other. Which model holds that link, and in what form, is a modeling decision with real consequences — and it's where relational and document databases differ most, so the family guides cover it in depth.
+
+### Declaring a relation
+
+You declare a relation with two kinds of field:
+
+- A **relation field** — a virtual field typed as the related model (for example, `author User`). It has no storage of its own; it tells Prisma Next how to navigate the connection.
+- A field that **stores the connection** — the scalar that actually holds the link (for example, `authorId`). It typically references the other model's primary key, though it can point at any unique field.
+
+The `@relation` attribute ties them together with a **directional** vocabulary: `from` names the local field that holds the link, and `to` names the field it points at. Omit `to` and it defaults to the target model's `@id`.
+
+```prisma
+model Post {
+  id       Int  @id @default(autoincrement())
+  authorId Int
+  author   User @relation(from: [authorId], to: [id])
+}
+```
+
+Which model owns the relation, and how each cardinality is stored, is where the two database families diverge.
+
+## Next steps
+
+The same four building blocks — models, primary keys, scalar fields, and relations — apply to every Prisma Next schema. Where they diverge is in how you model relations, so continue with the guide for your database:
+
+- [Relational data modeling](/orm/next/data-modeling/relational-databases) — one-to-one, one-to-many, many-to-many, and polymorphic relations for PostgreSQL and other SQL targets, including how to pick which side stores the relation.
+- [MongoDB data modeling](/orm/next/data-modeling/mongodb) — the same shapes in the document family, plus the central decision: embed or reference.

apps/docs/content/docs/orm/next/data-modeling/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Data modeling",
+  "pages": ["index", "relational-databases", "mongodb"]
+}