AirdraftAirdraft
Get started
All guides

Defining Your Schema

Create collections and fields in airdraft.schema.json or using the visual Schema Editor in the dashboard.

3 min read472 words

The schema is the foundation of Airdraft. It defines every collection (content type) and the fields within each one. Everything — the editor UI, the API responses, TypeScript types — is derived from this schema.

The schema file

The schema lives in airdraft.schema.json at your project root. It's a plain JSON file you can commit to version control.

{
  "$schema": "https://airdraft.space/schema/v1",
  "version": 1,
  "collections": {
    "posts": {
      "path": "content/posts/{slug}.mdx",
      "format": "mdx",
      "publish": true,
      "slugSource": "title",
      "fields": {
        "title": { "type": "string", "required": true },
        "excerpt": { "type": "string" },
        "body": { "type": "rich-text" },
        "cover": { "type": "media" },
        "tags": { "type": "multiselect" },
        "author": { "type": "relation", "collection": "authors" }
      }
    },
    "authors": {
      "path": "content/authors/{slug}.json",
      "format": "json",
      "fields": {
        "name": { "type": "string", "required": true },
        "bio": { "type": "text" },
        "avatar": { "type": "media" }
      }
    }
  }
}

Note: Both collections and fields are plain JSON objects (keyed by name), not arrays.

Collection properties

Property Type Description
path string File path template for file-based storage. Use {slug} as the entry identifier placeholder.
format mdx | md | json | yaml File format (file-based adapters only).
publish boolean Enable draft/published state for this collection.
slugSource string Field to auto-generate the slug from on entry creation.
label string Display name shown in the editor UI. Defaults to the collection key.
titleField string Field used as the display title in the entry list. Defaults to "title".
defaultSort SortField | SortField[] Default sort order for the collection list.
previewUrl string Preview URL template, e.g. "/blog/{slug}".
fields Record<string, FieldConfig> The fields for this collection.

Field types

Type Description
string Single-line text
text Multi-line plain text (textarea)
rich-text Full rich-text editor — stores HTML/MDX; contributes to wordCount
number Integer or decimal
boolean True/false toggle
date Date picker (ISO date string)
datetime Date + time picker (ISO datetime string)
url URL input — validates https://… or /…
select Single-value dropdown with predefined options
multiselect Multi-value tag selector
list Array of plain string values
media Single media file; add "multiple": true for multi-file
relation Reference to an entry in another collection
relations Multi-reference — array of related entries
object Nested sub-object with its own fields map
blocks Structured nested object or repeatable array
image (deprecated — use media instead)

Field config properties

{
  "title": {
    "type": "string",
    "label": "Post title",
    "required": true
  },
  "cover": {
    "type": "media",
    "multiple": false,
    "accept": "image/*"
  },
  "tags": {
    "type": "multiselect",
    "options": [
      { "label": "Tutorial", "value": "tutorial" },
      { "label": "News", "value": "news" }
    ]
  },
  "author": {
    "type": "relation",
    "collection": "authors"
  }
}
Property Description
type One of the field types above.
label Display label in the editor. Defaults to the field key.
required Whether the field must have a value.
multiple For media: accept multiple files.
accept For media: MIME type filter (e.g. "image/*").
options For select/multiselect: array of { label, value } objects.
collection For relation/relations: name of the referenced collection.

Using the visual Schema Editor

If you have @airdraft/plugin-schema-editor installed (self-hosted) or are using Airdraft Cloud, you can manage the schema from the dashboard.

  1. Go to your project's Schema tab.
  2. Click New collection.
  3. Enter a name — the file path auto-populates as content/{name}/{slug}.mdx.
  4. Click Add field, select a type, and configure it.
  5. Click Save — airdraft.schema.json is updated immediately.

Tip: The editor and airdraft.schema.json are always in sync. You can edit the file directly or use the UI — both work.

Relations between collections

Use the relation type to link entries. When querying, pass ?expand=author to inline the full related entry object:

const result = await client.entries.get('posts', 'my-post', { expand: 'author' })
// result.data.author → { slug: 'jane-doe', data: { name: 'Jane Doe', ... } }

TypeScript type generation

Generate TypeScript interfaces from your schema:

npx airdraft generate-types

Or use InferCollectionData<C> from @airdraft/core at build time:

import { asCollectionConfig, InferCollectionData } from '@airdraft/core'
import schema from './airdraft.schema.json'

const postsConfig = asCollectionConfig(schema.collections.posts)
type PostData = InferCollectionData<typeof postsConfig>
// → { title: string; excerpt?: string; body?: string; cover?: string; tags?: string[] }

Validating your schema

npx airdraft validate

Checks that airdraft.schema.json is valid and that all relation fields reference existing collections.

Resources

What's next