> ## Documentation Index
> Fetch the complete documentation index at: https://urbackend-mintlify-1dc05325.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Collections & Schemas

> Collections are the tables of urBackend. You create them in the dashboard, optionally define a schema, and interact with them through the REST API.

## What is a collection?

A collection is a named container for JSON documents — conceptually equivalent to a MongoDB collection or a database table. Every collection you create in the dashboard gets its own REST endpoint at:

```
/api/data/:collectionName
```

**Collections must be created in the dashboard before you can write to them.** The API will reject requests to endpoints that do not correspond to a registered collection. Creating a collection registers it under your project and connects it to your MongoDB database.

<Tip>
  Prefer designing a whole set of collections at once from a natural-language description? Use the [AI Collection Creator](/guides/ai-collection-creator) as an alternative to the manual field builder.
</Tip>

<Warning>
  The `users` collection is reserved. All user account operations go through `/api/userAuth/*`. Requests to `/api/data/users` or any path starting with `/api/data/users` are blocked with a `403` response.
</Warning>

## Flexible mode vs. schema-enforced mode

When you create a collection, you choose whether to define a schema.

**Flexible mode (no schema):** urBackend stores whatever JSON you send. There is no type validation. This is useful for prototyping or for collections where the shape varies between documents.

**Schema-enforced mode:** You define the fields, their types, and any constraints. The API validates every incoming document against the schema before saving. This prevents bad data and enables features like required fields and unique constraints.

You can switch between modes and evolve your schema over time from the dashboard.

## Supported field types

| Type      | Description                                   | Example JSON value            |
| --------- | --------------------------------------------- | ----------------------------- |
| `String`  | Text data                                     | `"Hello World"`               |
| `Number`  | Integer or decimal                            | `19.99`                       |
| `Boolean` | True or false                                 | `true`                        |
| `Date`    | ISO date string or valid date value           | `"2024-03-07"`                |
| `Object`  | Nested JSON structure                         | `{ "views": 10, "likes": 4 }` |
| `Array`   | List of values                                | `["electronics", "deals"]`    |
| `Ref`     | MongoDB ObjectId referencing another document | `"642f9abc1234567890abcdef"`  |

### Type matching rules

The schema engine is strict about types:

* A `String` field must receive a string — `"42"` is valid, `42` is not.
* A `Number` field must receive a number — not a stringified number.
* A `Boolean` field must receive `true` or `false`, not `"true"` or `1`.
* An `Object` field must receive a JSON object `{}`.
* An `Array` field must receive a JSON array `[]`.
* A `Ref` field should store a valid MongoDB ObjectId string.

Sending the wrong type returns a `400` validation error.

## System-managed fields

urBackend adds the `isDeleted` (Boolean, default `false`) and `deletedAt` (Date, default `null`) fields to every collection to manage soft deletes. The system strictly manages these fields so you cannot set, modify, or filter by them directly from the client.

<Note>
  Documents with `isDeleted: true` are excluded from normal read queries by default. To view them, you must use the `include_deleted=true` query parameter.
</Note>

## Defining field constraints

### Required fields

Mark a field as **required** in the dashboard to prevent documents from being saved without it. Any `POST` or `PUT` request missing a required field returns:

```json theme={null}
{
  "success": false,
  "message": "Validation failed: email is required"
}
```

### Unique constraints

Mark a field as **unique** to enforce that no two documents in the collection share the same value for that field. This is enforced at the database level and is useful for fields like `username` or `email` in custom collections.

### Default values

Set a **default** on any non-required `String`, `Number`, or `Boolean` field. When a document is inserted without that field, urBackend stores the default value instead of leaving it unset.

Defaults are available in both the manual collection builder and the AI Collection Creator. In the manual builder, the `Default` column appears next to each field row and accepts a value that matches the field's type. In the AI Collection Creator, defaults are proposed automatically for optional fields where they make sense.

Rules:

* Defaults are only supported on `String`, `Number`, and `Boolean` fields. `Date`, `Ref`, `Array`, and `Object` fields cannot have defaults.
* Defaults are only allowed on non-required fields. Marking a field as required clears any default that was set.
* The default value's type must match the field type — a `Number` field cannot default to a string.

## Collections must have at least one field

A collection must be created with at least one field. Requests to create or edit a collection with an empty schema are rejected with `400`:

```json theme={null}
{
  "success": false,
  "message": "At least one field is required"
}
```

The dashboard blocks the **Save Collection** action when no fields are defined, and the AI Collection Creator will not finalize an empty schema.

## Field type examples

### String

```json theme={null}
{
  "title": "Getting started with urBackend",
  "slug": "getting-started"
}
```

### Number

```json theme={null}
{
  "price": 19.99,
  "quantity": 100
}
```

### Boolean

```json theme={null}
{
  "isPublished": true,
  "isPremium": false
}
```

### Date

```json theme={null}
{
  "publishedAt": "2024-03-07",
  "expiresAt": "2025-01-01T00:00:00.000Z"
}
```

### Object

Use the `Object` type for nested structures. In the dashboard, add sub-fields inside the object field. In the API, send a regular nested JSON object:

```json theme={null}
{
  "profile": {
    "avatar": "https://cdn.example.com/avatar.png",
    "bio": "Developer and coffee enthusiast"
  }
}
```

### Array

```json theme={null}
{
  "tags": ["tech", "ai", "tutorial"],
  "scores": [98, 87, 92]
}
```

### Ref

Use `Ref` to store a reference to a document in another collection. Store the target document's `_id` as a string:

```json theme={null}
{
  "content": "Great post!",
  "authorId": "642f9abc1234567890abcdef",
  "postId": "651a7def9876543210fedcba"
}
```

<Tip>
  References are stored as plain ObjectId strings. urBackend does not automatically populate or join referenced documents in GET responses — your application is responsible for resolving references if needed.
</Tip>

## The users collection

The `users` collection has a fixed schema contract required by the auth system:

* `email` — required `String`
* `password` — required `String`

You can add additional fields (such as `name`, `avatar`, or `role`) on top of this contract. Define the full schema in the dashboard before enabling authentication to ensure your custom fields are validated correctly.

<Note>
  Always interact with user records through `/api/userAuth/*` endpoints, not through the data API. The data API blocks all access to `/api/data/users*`.
</Note>