> For the complete documentation index, see [llms.txt](https://flapjax.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flapjax.gitbook.io/docs/your-data/stacks/schema.md).

# Stacks Schema

A **stack** is a custom table of records. A "Products" catalogue, a "Page Views" log, an "Account Flags" list. Its **schema** is the set of attributes, meaning columns, that each record can hold.

This page covers creating a stack, defining and ordering its attributes, and the per-stack retention and auto-create settings.

To manage existing stacks, including the list, tags, search and actions, see [Browsing Stacks](/docs/your-data/stacks/browsing-stacks.md). For the person-side companion, see [People Attributes](/docs/your-data/people/attributes.md).

***

### Creating a Stack

Click **New stack** on the stacks list. The form asks for:

* **Plural name**, the plural form shown in lists and the sidebar, such as "Products".
* **Singular name**, the singular form, such as "Product".
* **Stack type**, one of **Items**, **Events** or **Signals**. You set this once and it stays **locked after creation**.
* **Key**, a unique API identifier. Leave it blank and Flapjax generates one from the plural name, lowercased with underscores for spaces.
* **Emoji**, **colour**, **description** and **tags**, all optional.

The stack type decides **who may write records and how**. Items allow full create, read, update and delete. Events are create-only, so a written record stays as it is. Signals are read-only to clients and get written by automations alone.

Read the worked examples for each type in [Browsing Stacks → Stack Types](/docs/your-data/stacks/browsing-stacks.md#stack-types) before you choose.

A new stack opens on its **Settings** page. Configure its attributes and options there.

***

### Viewing Attributes

Open a stack's **Settings** and go to the **Attributes** tab. The list splits into two groups.

**System attributes** are always present and read-only: **Record ID**, **Created At**, **External ID** and **Source Type**. They are built in, so you cannot edit, reorder or delete them.

**Custom attributes** are the schema fields you define. Each row shows its name, a **Custom** tag and a row menu with Update, Set as primary and Delete. A cube icon marks the current **primary** attribute.

**Drag and drop** custom attributes to reorder them. Flapjax saves that order on the server, so it holds across sessions.

The toolbar carries an **API reference** button. It shows an example record JSON payload keyed by your attributes, which helps when you create or update records over the API.

***

### Creating an Attribute

Click **New attribute** in the top-right corner.

#### Basic Fields

* **Data type**, the kind of data the attribute holds. See Data Types below. The available types depend on the stack type, and the choice stays locked after creation.
* **Name**, a human-readable label.
* **Description**, an optional explanation of the attribute's purpose, up to 500 characters.
* **Key**, a unique identifier generated from the name. Lowercase letters, numbers and underscores, 3 to 50 characters, unique inside the stack. Locked after creation.

#### Options

* **Is Required** makes the field mandatory on every record. Not available for relationship types. You **can change it later**, and turning it on leaves existing records without a value alone.
* **Is Unique** stops two records in the stack sharing a value. Not available for relationship types. Locked after creation.
* **Default Value** assigns a value to new records on its own. Available on fields that are neither unique nor a relationship type, since a unique attribute cannot carry a default.

Your first attribute becomes the **primary** attribute, the field that represents a record at a glance. Reassign the primary later from the row menu.

#### Data Types

| Type                         | Description                                       |
| ---------------------------- | ------------------------------------------------- |
| **Text (String)**            | Free-form text                                    |
| **Number (Integer)**         | Whole numbers                                     |
| **Decimal (Float)**          | Numbers with decimal places                       |
| **True/False (Boolean)**     | `true` or `false`                                 |
| **Hour**                     | Hour of day, 0 to 23                              |
| **Date**                     | A calendar date                                   |
| **Date & Time**              | A date with a specific time                       |
| **Single Choice (Select)**   | One value from a list of options you define       |
| **Multiple Choice (Select)** | A set of values from a list you define            |
| **Country List**             | A country code                                    |
| **Currency List**            | A currency code                                   |
| **Encrypted Text**           | Text stored encrypted at rest, for sensitive data |
| **Related Person (One)**     | A link to a single person                         |
| **Related People (Many)**    | Links to multiple people                          |
| **Related Stack**            | A link to one or many records in another stack    |

Pick **Single Choice** or **Multiple Choice** and Flapjax asks you to define the options. Pick a relationship type and it asks you to configure the reference target, covered below.

**Related Person (One)** and **Related People (Many)** exist on stack attributes only. A record can point at a person. A person attribute cannot point back at a person. For the full type catalogue and how each type behaves in rules and automations, see [Data Types](/docs/core-concepts/data-types.md#2-the-full-catalogue).

Click **Save** to create the attribute. Turn on **Create more** in the footer to keep the form open and add several attributes in a row.

***

### Relationship Attribute Configuration

Three data types turn an attribute into a **reference** to another entity:

* **Related Person (One)** points at a single person.
* **Related People (Many)** points at several people.
* **Related Stack** points at one or many records in another stack. Pick this type and you choose the **target stack** plus whether the link holds one record or many.

A **Related Stack** attribute stores two things in its configuration: a relation type of one or many, and the target stack. Relationship attributes cannot be marked required or unique, and they take no default value. For how references get stored and resolved, plus their traversal limits in filters, see [Relationships](/docs/core-concepts/relationships.md#2-reference-attributes).

***

### Editing an Attribute

Click a custom attribute to open its form. An existing attribute lets you update the **name**, the **description**, the **default value**, the **required** flag, and the **configuration** on relationship and choice types.

The **data type**, **key** and **unique** settings stay **locked after creation**. They are not part of the update request.

To change a locked setting, delete the attribute and recreate it. **Deleting** from the row menu removes the attribute and its data from every record in the stack, permanently. Flapjax asks you to confirm.

***

### Setting the Primary Attribute

Use **Set as primary** in a custom attribute's row menu. That field then represents a record at a glance. Only one attribute holds primary at a time.

***

### Data Retention (Auto-Delete)

The stack's **Settings** tab carries an **Automatic Record Deletion** switch. Turn it on and Flapjax deletes records older than the retention period you set.

* Choose a preset period of **1 Month (30 days)**, **3 Months (90 days)**, **6 Months (180 days)** or **1 Year (365 days)**. You can enter a **custom** number of days instead, greater than 0.
* A warning appears before you save. Turning retention on, or shortening it, removes matching records for good.
* Turning auto-delete off stops future deletions and keeps the records you still have. Flapjax clears the retention period at the same time.

{% hint style="warning" %}
Auto-delete is permanent. Turn it on, or shorten the period, and records older than that period go away with no recovery.
{% endhint %}

***

### Record Auto-Creation

The **Auto-Create Records** switch handles references to records that do not exist yet. Another entity points at a record in this stack by external ID, and Flapjax finds nothing there.

Turn the switch on and Flapjax creates that record as a minimal stub and links it, so you never have to create it up front. A later write fills the stub with real data and keeps the link intact.

The switch saves as soon as you flip it. See [Relationships → Auto-create](/docs/core-concepts/relationships.md#4-auto-create--normalization-on-write) for how references and auto-creation work across the platform.

***

### Deleting a Stack

The Settings tab has a danger zone with **Delete stack permanently**. Flapjax asks you to confirm.

Deleting a stack removes all of its records, attributes and metadata. Person and stack attributes elsewhere that reference this stack get cleared.

{% hint style="info" %}
**Tip:** API calls and automation configurations reference a field by its attribute key, and the stack key identifies the stack itself. Plan both carefully, since neither changes after creation.
{% endhint %}