Schema

The schema is your project’s data model. It describes:

Structure: what entities exist (product, order, supplier, etc.)
Attributes: what fields each entity has (name, price, status, etc.)
Semantics: how data is stored (dataType) and edited (inputType)
Relationships: how entities connect (single or multiple)
Scope behavior: whether a value is global, local, or relational

The same definition drives Desk’s lists and forms, the generated GraphQL API, and every agent that reads your project: a knowledge graph of the business, expressed as entities and relationships. A first schema that stores records faithfully is a strong start. The schema that answers weekly commercial questions is usually a later revision — see iterating your schema.

A project’s schema is changed in one of two ways, chosen under Schema Management: in the app with the Flexkit Agent (the default for new projects), or from code with flexkit deploy.

Build your schema with the agent

You do not need to write code to build or change a schema. Start a project from the commerce starter or a description of your business, then ask the agent in the AI chat whenever the model needs to grow:

“Add a care instructions field to Product.”
“Track which warehouse each purchase order is delivered to.”
“Add a Germany market with prices in euros.”
“Create a Supplier entity and link it to Product.”

The agent turns the request into schema changes, checks them, and shows a review card listing every entity and attribute it adds, changes or removes. Nothing changes until an owner or developer approves the card. Desk and the agent pick up the new schema as soon as it is applied. Removing an entity or field loses access to its data, so the agent asks you to confirm a removal explicitly and flags it as a breaking change. See changing the schema from the chat.

Every change, from the agent or from code, is recorded as a deployment with who made it.

Define the schema in code

The rest of this section describes the schema as code, for developers whose project is managed from code. The same concepts apply to a schema built with the agent; the code reference shows every option the schema supports.

Quick Start

The config lives in flexkit.config.ts and is pure data: entities, attributes, scopes and spaces. There are no React components in it.

import { defineConfig, defineEntity } from '@flexkit/schema';
 
const products = defineEntity({
  name: 'product',
  plural: 'products',
  display: 'name',
  menu: { label: 'Products', group: 'catalog', icon: 'Tag' },
  attributes: [
    {
      name: 'name',
      label: 'Name',
      scope: 'local',
      dataType: 'string',
      inputType: 'text',
      searchable: true,
      defaultValue: '',
      validation: (z) => z.string().min(1),
      options: {
        comment: 'Public product name',
        size: 260,
      },
    },
    {
      name: 'sku',
      label: 'SKU',
      scope: 'global',
      dataType: 'string',
      inputType: 'text',
      unique: true,
      defaultValue: '',
    },
    {
      name: 'price',
      label: 'Price',
      scope: 'local',
      dataType: 'float',
      inputType: 'number',
      defaultValue: '',
      validation: (z) => z.number().min(0),
      options: {
        comment: 'Current selling price',
        min: 0,
      },
    },
  ],
});
 
export default defineConfig({
  title: 'My Project',
  projectId: 'myprojectid',
  menuGroups: [{ name: 'catalog', title: 'Catalog' }],
  scopes: [
    { name: 'default', label: 'Default', isDefault: true },
    { name: 'es', label: 'Spain' },
    { name: 'fr', label: 'France' },
  ],
  schema: [products],
});

defineConfig and defineEntity are exported by @flexkit/schema and re-exported by @flexkit/studio, so either import works. Validation rules are written with Zod and compiled to JSON Schema on deploy; the messages editors see (“Name is required”, “Price must be at least 0”) are generated from the attribute label, so you do not write them yourself. See Validation.

Deploy to see it. The Studio renders the schema that is deployed for the project, not the file on disk. After editing flexkit.config.ts, run flexkit deploy; the Studio picks up the new schema on its next load.

Core Model

Project config (defineConfig) wires the project id, title, menu groups, scopes, spaces, and schema.
Entity (defineEntity) is a collection/table-like model.
Attribute config defines storage type, form input type, validation, and behavior flags.
Relationship attributes link entities through relationship.entity, relationship.mode, and relationship.field.

A living model

Chat and automations query only what the schema exposes. If an agent can count order lines but cannot name a bestseller, the records are present and the question is not yet modeled — an inverse relationship, a sortable total, or a field comment is often the missing piece.

Treat those gaps as the next design pass. Ask the agent for the missing field or relationship (or, for a code-managed schema, give a coding agent the question, the agent’s reply, and your schema files and deploy the change); fill the new fields; ask again. The walkthrough is in iterating your schema.

Teams new to Flexkit often expect the first deploy to answer every prompt. The intended path is the opposite: ship a usable model, work with real questions, then add the data points those questions need.