ObjectStackSolution Blueprint
Solution Blueprint protocol schemas
Solution Blueprint Schema (ADR-0033 §4 — plan-first authoring)
The structured-output target an AI agent emits for a high-level goal
("build me a project-management system") instead of transcribing a field
list. It is a simplified proposal shape — deliberately lighter than the
full ObjectSchema / ViewSchema / DashboardSchema.
The apply_blueprint tool expands each entry into a proper metadata body
and stages it as a draft (so the per-type Zod schema still validates the
real artifact at write time).
The blueprint is never persisted on its own: the agent presents it for
conversational confirmation/edit (cheap), and only on human approval does it
batch-draft. This is the safety valve for low-specificity input.
Source: packages/spec/src/ai/solution-blueprint.zod.ts
TypeScript Usage
import { BlueprintApp, BlueprintDashboard, BlueprintField, BlueprintNavItem, BlueprintObject, BlueprintSeed, BlueprintView, BlueprintWidgetCondition, SolutionBlueprint, SolutionBlueprintStrict } from '@objectstack/spec/ai';
import type { BlueprintApp, BlueprintDashboard, BlueprintField, BlueprintNavItem, BlueprintObject, BlueprintSeed, BlueprintView, BlueprintWidgetCondition, SolutionBlueprint, SolutionBlueprintStrict } from '@objectstack/spec/ai';
// Validate data
const result = BlueprintApp.parse(data);BlueprintApp
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| name | string | ✅ | App machine name (snake_case) |
| label | string | optional | App display label |
| icon | string | optional | Lucide icon for the App Launcher |
| nav | Object[] | optional | Navigation entries; omit to auto-surface every created object and dashboard |
BlueprintDashboard
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| name | string | ✅ | Dashboard machine name (snake_case) |
| label | string | optional | Human-readable dashboard label |
| widgets | Object[] | optional | Widgets to place on the dashboard |
BlueprintField
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| name | string | ✅ | Field machine name (snake_case) |
| label | string | optional | Human-readable field label |
| type | Enum<'text' | 'textarea' | 'email' | 'url' | 'phone' | 'password' | 'secret' | 'markdown' | 'html' | 'richtext' | 'number' | 'currency' | 'percent' | 'date' | 'datetime' | 'time' | 'boolean' | 'toggle' | 'select' | 'multiselect' | 'radio' | 'checkboxes' | 'lookup' | 'master_detail' | 'tree' | 'user' | 'image' | 'file' | 'avatar' | 'video' | 'audio' | 'formula' | 'summary' | 'autonumber' | 'composite' | 'repeater' | 'record' | 'location' | 'address' | 'code' | 'json' | 'color' | 'rating' | 'slider' | 'signature' | 'qrcode' | 'progress' | 'tags' | 'vector'> | ✅ | Field data type |
| required | boolean | optional | Whether the field is required |
| reference | string | optional | Target object name for lookup / master_detail relationship fields |
| options | Object[] | optional | Choices for select / multiselect / radio fields |
BlueprintNavItem
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| type | Enum<'object' | 'dashboard'> | ✅ | What this nav entry opens |
| target | string | ✅ | Object or dashboard machine name to surface (snake_case) |
| label | string | optional | Nav entry label (defaults to the target label/name) |
| icon | string | optional | Lucide icon name for the nav entry |
BlueprintObject
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| name | string | ✅ | Object machine name (snake_case) |
| label | string | optional | Human-readable singular label |
| description | string | optional | What this object represents |
| fields | Object[] | ✅ | Fields to create on the object |
| nameField | string | optional | The record title field — which field holds the human-readable name shown on cards, lookup chips, breadcrumbs and search (ADR-0079). Set it to the object's text label field (e.g. "product_name"). For a numbered entity (invoice/ticket), set it to a formula field that composes number + name (e.g. "{order_no} · {customer}"). Omitting it lets the platform auto-pick a text field, but declaring it is strongly preferred. |
BlueprintSeed
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| object | string | ✅ | Target object name (snake_case) |
| records | Record<string, any>[] | ✅ | Rows to seed |
BlueprintView
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| object | string | ✅ | Object this view displays (snake_case) |
| name | string | ✅ | View machine name (snake_case) |
| label | string | optional | Human-readable view label |
| type | Enum<'list' | 'form' | 'kanban' | 'calendar' | 'gallery' | 'gantt'> | ✅ | View kind. Pick the surface that fits the data: "gallery" for a visual card/cover browse when the user asks for a 画廊/相册/卡片墙/封面/海报/图集 (a gallery / card wall / cover / poster grid) or the object has an image/avatar/file field worth showing as a card cover; "gantt" for a 甘特图/时间线/排期 (timeline / schedule) when the object has BOTH a start and an end date field; "kanban" for a board grouped by a status/select field; "calendar" for a single-date schedule; "form" for a record editor; else "list". |
| columns | string[] | optional | Field names shown as columns (in order). For a gallery, INCLUDE the image/avatar/file field (it becomes the card cover); for a gantt, INCLUDE the start date column before the end date column. |
| groupBy | string | optional | REQUIRED for kanban views: the select/status field whose options become the board columns (e.g. "stage", "status"). Without it a kanban renders as a plain list. Optional for gantt (groups leaf tasks into summary rows). |
BlueprintWidgetCondition
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| field | string | ✅ | Field on the widget object to filter by (e.g. "stock_quantity", "status") |
| op | Enum<'lt' | 'lte' | 'gt' | 'gte' | 'eq' | 'ne'> | ✅ | Comparison operator |
| value | number | string | boolean | ✅ | Comparison value (e.g. 10, "open") |
SolutionBlueprint
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| summary | string | ✅ | One-line description of the proposed solution |
| assumptions | string[] | ✅ | Design assumptions made from the underspecified goal |
| questions | string[] | optional | At most 1-2 structure-deciding questions to confirm before building |
| objects | Object[] | ✅ | Objects (tables) to create |
| views | Object[] | optional | Views to create |
| dashboards | Object[] | optional | Dashboards to create |
| app | Object | optional | The navigation shell (app) that surfaces the created objects/dashboards to end users |
| seedData | Object[] | optional | Suggested seed data (reported, not auto-applied in Phase C) |
SolutionBlueprintStrict
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| summary | string | ✅ | One-line description of the proposed solution |
| assumptions | string[] | ✅ | Design assumptions made from the underspecified goal |
| questions | string[] | null | ✅ | At most 1-2 structure-deciding questions to confirm before building, or null |
| objects | Object[] | ✅ | Objects (tables) to create |
| views | Object[] | null | ✅ | Views to create, or null |
| dashboards | Object[] | null | ✅ | Dashboards to create, or null |
| app | Object | null | ✅ | The navigation shell (app) that surfaces the created objects/dashboards, or null |