Skip to main content
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',
});
EnvironmentBehavior
DevelopmentRegenerates .forestadmin-schema.json on every restart
Remote / productionNever regenerates, uses the schema file deployed alongside the code
Schema file versioning lifecycle

​
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