metabuilder/packages/SEED_FORMAT.md

Package Seed Data Format

Overview

Each MetaBuilder package can include seed data - initial records that populate the database when the system bootstraps. Seed data is:

• Simple JSON or YAML files - Just data, no code
• Entity-specific - One folder per entity type (e.g., page-config, workflow)
• Loaded automatically - The DBAL seed orchestration loads them in order
• Idempotent - Safe to run multiple times (existing records are skipped)

Structure

packages/[packageId]/
├── seed/
│   ├── metadata.json          [Required - manifest file]
│   ├── page-config.json       [Optional - PageConfig records]
│   ├── workflow.json          [Optional - Workflow records]
│   └── ...other entities...
└── ...other package files...

metadata.json Format

The metadata.json file tells the system:

1. Which data files to load
2. Basic package information
3. Permission requirements

{
  "$schema": "https://metabuilder.dev/schemas/package-metadata.schema.json",
  "packageId": "ui_home",
  "name": "Home Page",
  "version": "1.0.0",
  "description": "Seed data for ui_home package",
  "author": "MetaBuilder Contributors",
  "license": "MIT",
  "category": "ui",
  "minLevel": 0,
  "primary": true,
  "keywords": ["home", "landing", "seed-data"],
  "seed": {
    "schema": "page-config.json"
  }
}

Fields

Field	Type	Required	Description
$schema	string	No	JSON schema URL for validation
packageId	string	Yes	Must match package folder name
name	string	Yes	Human-readable package name
version	string	Yes	Semantic version (e.g., "1.0.0")
description	string	Yes	What this seed data does
author	string	Yes	Creator/maintainer
license	string	No	Software license (MIT, Apache-2.0, etc.)
category	string	No	Package category (ui, admin, system, etc.)
minLevel	number	No	Minimum permission level required (0-5)
primary	boolean	No	Is this a core system package?
keywords	array	No	Search keywords
seed.schema	string	No	Reference to data file (if any)

Data File Format

Each data file contains an array of entity records:

[
  {
    "id": "page_ui_home_root",
    "path": "/",
    "title": "MetaBuilder",
    "component": "home_page",
    "level": 0,
    "requiresAuth": false,
    "isPublished": true
  }
]

Important Rules

1. Array format - Always a JSON array, even if one record
2. No code - Only JSON data, no TypeScript functions
3. Entity fields - Use fields defined in the DBAL entity schema
4. No hardcoding - Values can be customized via admin panel after seed load

Entity Types

Common entity types that packages seed:

Entity	File	Description
PageConfig	page-config.json	Routes/pages that packages expose
Workflow	workflow.json	Automation workflows
Credential	credential.json	API credentials or secrets
ComponentConfig	component-config.json	Reusable component configurations
Notification	notification.json	Notification templates

How Seed Loading Works

1. System calls POST /api/bootstrap
2. DBAL reads /dbal/shared/seeds/database/installed_packages.yaml (list of packages to install)
3. For each package in the list:
   • Reads seed/metadata.json
   • If seed.schema is specified, reads that data file
   • Creates records in database using DBAL client
   • Skips if records already exist (idempotent)
4. Returns success/error JSON response

Example: Page Config Seed

File: packages/my_package/seed/page-config.json

[
  {
    "id": "page_my_pkg_dashboard",
    "path": "/my-dashboard",
    "title": "My Dashboard",
    "description": "Custom dashboard for my package",
    "component": "my_dashboard_component",
    "level": 1,
    "requiresAuth": true,
    "isPublished": true
  }
]

This creates a new route /my-dashboard that loads the component defined in this package.

Do's and Don'ts

✅ DO:

• Keep seed files simple - just data
• Use one file per entity type
• Include metadata for every seed package
• Match entity field names exactly
• Use the admin panel to customize after bootstrap

❌ DON'T:

• Add code files to seed folder
• Create documentation markdown in seed folder
• Add nested folder structures
• Include scripts or utilities
• Hardcode sensitive data (use Credential entity instead)

Bootstrap API

Endpoint

POST /api/bootstrap

Response (Success)

{
  "success": true,
  "message": "Database seeded successfully",
  "packagesInstalled": 12,
  "recordsCreated": 45
}

Response (Error)

{
  "success": false,
  "error": "Failed to create PageConfig: Duplicate path '/'"
}

Multi-Entity Seed

If a package needs to seed multiple entity types:

packages/complex_package/
└── seed/
    ├── metadata.json
    ├── page-config.json      [Routes]
    ├── workflow.json         [Workflows]
    └── credential.json       [Credentials]

Update metadata.json to reference all:

{
  ...other fields...,
  "seed": {
    "pageConfig": "page-config.json",
    "workflow": "workflow.json",
    "credential": "credential.json"
  }
}

Then update /dbal/development/src/seeds/index.ts to load all referenced files.

Guidelines

1. Keep it minimal - Only include essential bootstrap data
2. Describe your data - Use meaningful field values, not placeholder text
3. Version your data - Update version in metadata when seed data changes
4. Test idempotency - Seed should be safe to run multiple times
5. Document changes - When modifying seed data, update the description field

See Also

• /dbal/development/src/seeds/index.ts - Seed orchestration implementation
• /dbal/shared/api/schema/entities/ - Entity definitions (source of truth for fields)
• /packages/ui_home/seed/ - Example: home page seed data
• CLAUDE.md - Seed folder guidelines and mistakes to avoid