.forestadmin-schema.json

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.

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

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.

const agent = createAgent({
  authSecret: process.env.FOREST_AUTH_SECRET,
  envSecret: process.env.FOREST_ENV_SECRET,
  isProduction: process.env.NODE_ENV === 'production',
});

# 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

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

Schema file versioning lifecycle — The schema file is generated on every restart in dev, then frozen and deployed alongside production code

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.

Do not edit .forestadmin-schema.json manually. Wrong syntax will break the UI.

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

Overview

Connect

Process

Build

Execute

Collaborate

Manage

Embed

Control

Project Settings

When the file is generated

Why versioning matters

What versioning the schema gives you

​When the file is generated

​Why versioning matters

​What versioning the schema gives you

When the file is generated

Why versioning matters

What versioning the schema gives you