---
title: 'Flexkit Schema Documentation'
description: 'Define entities, fields, and relationships in code — then refine the model as Chat and automations reveal the questions it should answer.'
---

import { Callout } from 'nextra/components';

# Flexkit Schema Documentation

Flexkit schemas define your data model in code. A schema describes:

- **Structure**: what entities exist (`product`, `deal`, `invoice`, 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 Studio, 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](/docs/schema/iterating-your-schema).

## Quick Start

```tsx
import { defineConfig, defineEntity } from '@flexkit/studio';

const products = defineEntity({
  name: 'product',
  plural: 'products',
  display: 'name',
  menu: { label: 'Products', group: 'catalog' },
  attributes: [
    {
      name: 'name',
      label: 'Name',
      scope: 'local',
      dataType: 'string',
      inputType: 'text',
      searchable: true,
      defaultValue: '',
      validation: (z) => z.string().min(1, { message: 'Name is required' }),
      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, { message: 'Price must be >= 0' }),
      options: {
        comment: 'Current selling price',
        min: 0,
      },
    },
  ],
});

export default defineConfig({
  title: 'My Project',
  projectId: 'myprojectid',
  basePath: '/studio',
  scopes: [
    { name: 'default', label: 'Default', isDefault: true },
    { name: 'es', label: 'Spain' },
    { name: 'fr', label: 'France' },
  ],
  schema: [products],
});
```

## Core Model

- **Project config** (`defineConfig`) wires project settings, scopes, extensions, 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. Give a coding agent the question, the agent’s reply, and your schema files; deploy the change; backfill the new fields; ask again. The walkthrough is in [iterating your schema](/docs/schema/iterating-your-schema).

<Callout type="info">
  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.
</Callout>

## More resources

- [Iterating your schema](/docs/schema/iterating-your-schema)
- [Schema Configuration](/docs/schema/schema-configuration)
- [Scopes](/docs/schema/scopes)
- [Entity Reference](/docs/schema/entity-reference)
- [Attribute Reference](/docs/schema/attribute-reference)
- [Conditional Fields](/docs/schema/conditional-fields)
- [Field Groups](/docs/schema/field-groups)
- [Data Types and Input Types](/docs/schema/data-types-and-input-types)
- [Relationships and Scopes](/docs/schema/relationships-and-scopes)
- [Schema Examples](/docs/schema/examples)


---

[View full sitemap](/docs/sitemap.md)