Schemas

A schema lists the fields that a collection stores. You write it as a plain object, and StarkForge turns it into a Mongoose model when the server starts. A field can also carry the Zod rule that checks request values for it, so one object says both how a value is stored and how it is validated.

A Small Schema

This articles collection stores a title, a slug, a status and private review notes. It uses each kind of field that a schema accepts:

// src/collections/articles.ts
import { collection, defineRoutes, fields } from "@starklabs/forge";
import { z } from "zod";

// A wrapped field: your own Mongoose definition and your own Zod rule in one object.
const slug = {
  mongoose: { type: String, required: true, unique: true, lowercase: true, trim: true },
  zod: z.string().trim().min(3).max(80).regex(/^[a-z0-9-]+$/, "Use lowercase letters, digits and dashes"),
};

export const articles = collection({
  type: "crud",
  route: "articles",
  model: "Article",
  schema: {
    // A helper: ready-made storage and validation.
    title: fields.requiredString,
    slug,
    // A plain Mongoose definition: storage only.
    status: { type: String, enum: ["draft", "published"], default: "draft" },
    // A secret: stored, but never returned and never sortable.
    reviewNotes: { type: String, select: false },
  },
  validations: {
    create: {
      title: fields.requiredString,
      slug,
      status: z.enum(["draft", "published"]).optional(),
      reviewNotes: z.string().optional(),
    },
  },
  routes: defineRoutes([
    { method: "get", path: "/", handler: "readAll", auth: "public" },
    { method: "get", path: "/:id", handler: "read", auth: "public" },
    { method: "post", path: "/", handler: "create", auth: "authenticated", roles: ["editor", "admin"], validation: "create" },
  ]),
});

title is a helper that comes with StarkForge. slug is a wrapped field that you write yourself, and the same object appears in schema and in validations. status and reviewNotes are plain Mongoose definitions.

A request signed in as an editor creates an article. The request has no status, so the Mongoose default fills it in, and reviewNotes is stored but does not come back:

POST /api/v1/articles
Content-Type: application/json

{
  "title": "Hello StarkForge",
  "slug": "hello-starkforge",
  "reviewNotes": "Check the intro"
}

HTTP/1.1 201 Created
Content-Type: application/json

{
  "success": true,
  "message": "Article created successfully.",
  "data": {
    "title": "Hello StarkForge",
    "slug": "hello-starkforge",
    "_id": "665f1c2e8b3a4d0012a10001",
    "status": "draft",
    "createdAt": "2026-01-15T10:30:00.000Z",
    "updatedAt": "2026-01-15T10:30:00.000Z"
  }
}

Three Ways to Write a Field

A helper is a wrapped field that StarkForge wrote for you. StarkForge recognizes a wrapped field by its two keys, mongoose and zod, and it needs both. Anything else in schema is a plain Mongoose definition, so every Mongoose field option works there, such as required, default, enum, index, ref and lowercase. The type can be a Mongoose type such as String, or its name as a string, such as "ObjectId".

A wrapper that has only one of the two keys fails when the server builds the app:

ConfigurationError (CONFIGURATION_ERROR): Schema field 'sku' has only one of 'mongoose' and 'zod'.
hint: A wrapped field needs both: { mongoose: { type: String }, zod: z.string() }. For a plain Mongoose definition, write it without the wrapper.

Where the Zod Rule Is Used

The zod half of a field does nothing by itself. StarkForge uses it in two places:

1. When you put the field into a group of validations, as title and slug are above.
2. When the built-in authentication builds its sign-up and profile rules from your user schema.

A crud route never derives its rules from the schema. It checks the body with the group that its validation key names, and with no group it accepts no body fields. The schema decides what can be stored, and the validation group decides what a route accepts, so the two lists must agree:

What StarkForge Adds

StarkForge builds every model with the Mongoose options timestamps and strict turned on. A collection cannot change them or pass other schema options such as virtuals, hooks or compound indexes: the schema is the list of fields and nothing else.

Unique Fields

A field with unique: true has a unique index. When a request would create a second document with the same value, the database refuses it, and StarkForge answers 409 with the code DUPLICATE_KEY. This request repeats the slug from the example above:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "success": false,
  "message": "An item with this slug already exists.",
  "code": "DUPLICATE_KEY",
  "hint": "'slug' is declared unique in the schema.",
  "details": {
    "fields": [
      "slug"
    ]
  },
  "requestId": "a2fcbda1-f1d5-4f1b-9b17-89b85374d2fe"
}

The hint and details appear only when exposeErrorDetails is on, which is the default outside production. A field that is unique but optional needs sparse: true, as sku has in the products collection. Without it, MongoDB treats a missing value as a value of its own, so only one document could leave the field out.

References Between Models

A reference stores the _id of a document from another model. Give the field type: "ObjectId" and a ref with the model name of the other collection. fields.userRef is a ready-made reference to a model named User, so it works only when your user model has that name.

// src/collections/comments.ts
import { collection, defineRoutes, fields } from "@starklabs/forge";

export const comments = collection({
  type: "crud",
  route: "comments",
  model: "Comment",
  schema: {
    body: fields.requiredString,
    // The id of a user. The helper points at the model named "User".
    author: fields.userRef,
    // The id of an article. For any other model, write the reference yourself.
    article: {
      mongoose: { type: "ObjectId", ref: "Article", required: true },
      zod: fields.requiredObjectId.zod,
    },
  },
  validations: {
    create: { body: fields.requiredString, article: fields.requiredObjectId },
  },
  routes: defineRoutes([
    { method: "get", path: "/", handler: "readAll", auth: "public" },
    { method: "post", path: "/", handler: "create", auth: "authenticated", validation: "create" },
  ]),
});

Reading the referenced document inside a response is called populating. Relations shows how to do it and which fields come back.

The User Model

Authentication needs a schema too. With builtinConfig.auth, you pass the schema of your user model as mongooseConfig, and StarkForge builds the sign-up and profile routes from it. The schema must define the email and password fields. This is the error when email is missing:

ConfigurationError (CONFIGURATION_ERROR): Invalid Forge configuration:
 - auth.mongooseConfig.schema must define the 'email' field.
hint: Fix the listed options in new Forge({...}).

Sign-up and profile updates accept only the fields that have a Zod rule. Build the user schema from helpers and wrapped fields: a plain Mongoose field is stored, but a client cannot set it through those routes. The Authentication page shows a complete user model.

Field Helpers

fields offers helpers for the common cases. Each one is a wrapped field, so the same name works in schema and in validations. In the names, required and optional say whether a value must be present, Index adds an index and Unique adds a unique index.

Two more exports hold the halves separately. mongooseFields has only the Mongoose half of each helper, and zodFields has only the Zod half.

Where to Go Next

:::