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

# .forestadmin-schema.json

> Reference for the auto-generated schema file describing your collections and customizations.

The `.forestadmin-schema.json` file is the canonical description of your agent's data model, the collections it exposes, the fields and their types, the relationships, and the customizations applied. It's auto-generated, versioned with your code, and read by the Forest API to render the UI for each environment.

<Note>
  The filename is `.forestadmin-schema.json` (the legacy naming is preserved to avoid breaking existing deployments). Treat it as a Forest-managed file.
</Note>

## When the file is generated

In **development environments only**, the agent regenerates `.forestadmin-schema.json` on every startup. It reflects:

* The state of your data sources (collections, fields, types, relationships)
* Your agent's customizations (actions, computed fields, segments, hooks)

In Node.js, the agent decides whether to regenerate based on the `isProduction` option passed to `createAgent`. In Ruby, generation is tied to the Rails environment, and you can also generate the file explicitly with a rake task.

<CodeGroup>
  ```typescript Node.js theme={null}
  const agent = createAgent({
    authSecret: process.env.FOREST_AUTH_SECRET,
    envSecret: process.env.FOREST_ENV_SECRET,
    isProduction: process.env.NODE_ENV === 'production',
  });
  ```

  ```bash Ruby theme={null}
  # In development, the schema is regenerated when the server boots.
  # In production, the agent uses the committed file and never regenerates it.
  # Generate it explicitly (without booting the server) with the rake task:
  rails forest_admin:schema:generate

  # Add debug=true to troubleshoot generation:
  rails forest_admin:schema:generate debug=true
  ```
</CodeGroup>

| Environment         | Behavior                                                            |
| ------------------- | ------------------------------------------------------------------- |
| Development         | Regenerates `.forestadmin-schema.json` on every restart             |
| Remote / production | Never regenerates, uses the schema file deployed alongside the code |

<Frame caption="The schema file is generated on every restart in dev, then frozen and deployed alongside production code">
  <img src="https://mintcdn.com/forest-chore-open-api/TmGmEqoffYUVv4Df/images/schema/under-the-hood-versioning.png?fit=max&auto=format&n=TmGmEqoffYUVv4Df&q=85&s=133132e4e0064620fe18fc5d2874537e" alt="Schema file versioning lifecycle" width="1885" height="946" data-path="images/schema/under-the-hood-versioning.png" />
</Frame>

## Why versioning matters

In **remote and production environments**, the agent does NOT regenerate the schema file. It uses the version that was deployed with your code. This means:

* You must commit `.forestadmin-schema.json` to version control
* You must deploy it alongside your agent code to every remote environment
* The file is the contract between your agent and the Forest API for that environment

If you change your data sources or customizations and don't redeploy the schema file, the production environment will keep serving the old schema, your changes won't show up in the UI.

<Warning>
  Do not edit `.forestadmin-schema.json` manually. Wrong syntax will break the UI.
</Warning>

## What versioning the schema gives you

Beyond keeping environments in sync, committing the schema file lets you:

* **Review schema changes in pull requests**, diffs show every collection, field, and relationship change before merge
* **Roll back schema regressions**, if a bad change breaks production, revert the commit
* **Audit historical schemas**, Git history shows the data model state at any past point