ObjectStackObjectStack

Solution Blueprint — AI Protocol reference

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.

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 { BlueprintAppSchema, BlueprintConditionSchema, BlueprintDashboardSchema, BlueprintFieldSchema, BlueprintNavItemSchema, BlueprintObjectSchema, BlueprintSeedSchema, BlueprintSummaryOperationsSchema, BlueprintViewSchema, BlueprintWidgetConditionSchema, SolutionBlueprintSchema, SolutionBlueprintStrictSchema } from '@objectstack/spec/ai';
import type { BlueprintApp, BlueprintCondition, BlueprintDashboard, BlueprintField, BlueprintNavItem, BlueprintObject, BlueprintSeed, BlueprintSummaryOperations, BlueprintView, BlueprintWidgetCondition, SolutionBlueprint, SolutionBlueprintStrict } from '@objectstack/spec/ai';

// Validate data
const result = BlueprintAppSchema.parse(data);

BlueprintApp

Properties

PropertyTypeRequiredDescription
namestring✅App machine name (snake_case)
labelstringoptionalApp display label
iconstringoptionalLucide icon for the App Launcher
nav{ type?: Enum<'object' | 'dashboard'>; target: string; label?: string; icon?: string; … }[]optionalNavigation entries; omit to auto-surface every created object and dashboard

Nested Shape: BlueprintApp.nav[number]

PropertyTypeRequiredDescription
typeEnum<'object' | 'dashboard'>optional (default: "object")What this nav entry opens
targetstring✅Object or dashboard machine name to surface (snake_case)
labelstringoptionalNav entry label. Optional: absent ⇒ the entry inherits the CURRENT label of what it opens at render time (a renamed target shows its new name); present ⇒ rendered verbatim, so never copy the target's label in as a default.
iconstringoptionalLucide icon name for the nav entry
viewNamestringoptionalFor type:"object" only — the views[].name this entry opens (e.g. "ticket_status_board"). Omit for the object's default list. SET it whenever this blueprint authors a kanban/calendar/gallery/gantt view the menu should reach: give the object ONE entry per view (a 「工单列表」 entry with no viewName plus a 「工单看板」 entry with viewName:"ticket_status_board"). Without it every entry on the same target opens the SAME default list, and a label/icon saying otherwise is decoration.

BlueprintCondition

Properties

PropertyTypeRequiredDescription
fieldstring✅Field on the target object to filter by (e.g. "stock_quantity", "status")
opEnum<'lt' | 'lte' | 'gt' | 'gte' | 'eq' | 'ne'>✅Comparison operator
valuenumber | string | boolean✅Comparison value — for a select field use its option VALUE, never its label (e.g. "completed", not "已完成")

BlueprintDashboard

Properties

PropertyTypeRequiredDescription
namestring✅Dashboard machine name (snake_case)
labelstringoptionalHuman-readable dashboard label
widgets{ id: string; title?: string; object?: string; chart?: Enum<'metric' | 'bar' | 'line' | 'pie' | 'table'>; … }[]optionalWidgets to place on the dashboard

Nested Shape: BlueprintDashboard.widgets[number]

PropertyTypeRequiredDescription
idstring✅Widget id (snake_case)
titlestringoptionalWidget title
objectstringoptionalSource object for the widget
chartEnum<'metric' | 'bar' | 'line' | 'pie' | 'table'>optionalWidget visualization
measurestringoptionalThe field this widget aggregates (e.g. "amount", "score"), or "count" to count records. Name the FIELD, not "total_amount" or "avg_score": how it is aggregated is what aggregate says, never this key. A "total revenue" widget sets measure:"amount" with aggregate:"sum"; an "average interview score" widget sets measure:"score" with aggregate:"avg"; a "number of deals" widget sets aggregate:"count" and needs no measure. measure:"count" is the legacy spelling of a record count: write aggregate:"count" instead. Beside "sum", "avg", "min" or "max", measure:"count" names no field to aggregate, so that widget is incomplete: a reader must refuse it, never sum, average or rank a record count. Omit for a count widget.
aggregateEnum<'sum' | 'avg' | 'min' | 'max' | 'count'>optionalHow the widget aggregates its records: "sum" = the total of the measure field; "avg" = its average; "min" / "max" = its smallest / largest value; "count" = the number of records the widget covers (after its condition). "sum", "avg", "min" and "max" need measure to name a numeric field of the widget's object. "count" needs no measure field: it counts records, and a field named in measure beside it is not read. Say what the widget computes: an average → "avg", a total → "sum", a highest / lowest value → "max" / "min", a number of records → "count". SET it on every widget that names a measure: a widget that names a measure and leaves this unset is incomplete, and a reader may refuse it; no default aggregation is promised. Only a count widget, which names no measure, may leave it unset.
groupBystringoptionalThe field to break the widget down by — the category or time axis (e.g. "stage", "created_at"). A "by status" chart MUST set this to the status field; the title and this field MUST name the SAME field. Omit for a single-number metric.
condition{ field: string; op: Enum<'lt' | 'lte' | 'gt' | 'gte' | 'eq' | 'ne'>; value: number | string | boolean }optionalRestrict WHICH records the widget counts/aggregates when its title implies a threshold or status (e.g. "stock below 10" → {field:"stock_quantity", op:"lt", value:10}; "open tickets" → {field:"status", op:"eq", value:"open"}). Without it the widget covers ALL records — so a "低于10的备件预警" / "overdue" card would wrongly count everything. Omit when the widget genuinely spans every record.

BlueprintField

Properties

PropertyTypeRequiredDescription
namestring✅Field machine name (snake_case)
labelstringoptionalHuman-readable field label
typeEnum<'text' | 'textarea' | 'email' | 'url' | 'phone' | 'password' | 'secret' | 'markdown' | 'html' | 'richtext' | 'number' | 'currency' | 'percent' | 'date' | … +35 more>✅Field data type
requiredbooleanoptionalWhether the field is required
referencestringoptionalTarget object name for lookup / master_detail relationship fields
options{ label: string; value: string; kind?: Enum<'open' | 'won' | 'lost'> }[]optionalChoices for select / multiselect / radio fields
summaryOperations{ object: string; function: Enum<'count' | 'sum' | 'avg' | 'min' | 'max'>; field?: string; relationshipField?: string; … }optionalREQUIRED when type is "summary" (a roll-up of child records: 任务总数 / 报名人数 / 合计金额 / 已完成任务数). Names the child object, the aggregation, and — for a qualified count/sum — the condition. A "summary" field without it materializes runtime-dead.
expressionstringoptionalREQUIRED when type is "formula" — the CEL body the field computes, e.g. "record.quantity * record.unit_price", or "record.order_no + ' · ' + record.customer.name" for a composed title. A formula reads a lookup / master_detail field's related record ONE hop through it — record.<lookup>.<field>, as record.customer.name above; the bare record.customer is the stored id, and a second hop (record.customer.owner.name) is refused at build. A "formula" field without it materializes runtime-dead: the engine builds its formula plan only from fields that HAVE an expression, so the field reads null everywhere, forever. Same failure shape as a "summary" with no summaryOperations. Note nameField on the object recommends a formula for numbered entities (invoice/ticket) — that formula needs THIS key, or the record title is blank on every card, lookup chip and breadcrumb.
defaultValueboolean | number | stringoptionalThe built field's default: the value a new record gets when it is created without one, carried into the object field as its defaultValue and stored as written. It must fit type, and only these types take one: "boolean" / "toggle" → true or false; "number" / "currency" / "percent" / "rating" / "slider" / "progress" → a number; "text" / "textarea" / "email" / "url" / "phone" / "markdown" / "html" / "richtext" / "code" / "color" → a string; "time" → a time of day, "HH:MM"; "select" / "radio" → the value of one of the field's own options, never its label. Every other type is refused by name: a date is fixed at design time, a reference or file names no record yet, a multi-value field stores a list, a formula / summary / autonumber is computed, and a credential, signature or structured value has no one value right for every record. A yes/no flag (是否完成 / 已付款 / is_active) is a "boolean" field that is never required (omit required or set it false) and carries defaultValue false: a required flag refuses the unchecked switch, and a flag with no default is empty, not false, on every record created without it, so a filter on false misses those records. Omit it for a field with no default.

Allowed Values: BlueprintField.type

  • 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

Nested Shape: BlueprintField.options[number]

PropertyTypeRequiredDescription
labelstring✅
valuestring✅
kindEnum<'open' | 'won' | 'lost'>optionalThe option's lifecycle category, REQUIRED on EVERY option of the field the object's stageField names. The object schema refuses the object unless the field stageField names is a single-value select or radio whose inline options EACH declare kind: "open" for a step on the way, "won" for the successful end (a deal's Closed Won, a task's Done, a case's Resolved), "lost" for the unsuccessful end (Closed Lost, Cancelled, Unqualified). Naming a multiselect / checkboxes / tags field that carries options is refused too: a record stands at one stage. Only a single-value select / radio field's options take it: omit it on a multiselect / checkboxes / tags field's options, where the field schema refuses it. Absent on any other select option reads as "open".

Nested Shape: BlueprintField.summaryOperations

PropertyTypeRequiredDescription
objectstring✅The CHILD object whose records are aggregated (snake_case). It must carry a lookup / master_detail field pointing back at this parent, or the roll-up never computes.
functionEnum<'count' | 'sum' | 'avg' | 'min' | 'max'>✅Aggregation: "数量 / 个数 / 计数" → count; "合计 / 总额 / 累计" → sum; "平均" → avg
fieldstringoptionalNumeric field on the CHILD object to aggregate. Ignored for "count" (pass "id" or omit it).
relationshipFieldstringoptionalThe child FK field pointing back at this parent. Auto-detected from the child's lookup / master_detail; set it only when the child has more than one reference to this parent.
conditions{ field: string; op: Enum<'lt' | 'lte' | 'gt' | 'gte' | 'eq' | 'ne'>; value: number | string | boolean }[]optionalCONDITIONAL roll-up: aggregate only the child rows matching these comparisons (ANDed). REQUIRED whenever the field name carries a qualifier — "已完成任务数 / 已收货金额 / 待处理工单数", any 已X / 未X / <某状态>的 count-or-sum → e.g. [{ field: "status", op: "eq", value: "completed" }]. WITHOUT it the roll-up silently counts EVERY child and reports a plausible-looking WRONG number, which is worse than a visible 0.
filteranyoptionalThe same predicate as a canonical query filter map (e.g. { status: "completed" }, { status: { $in: ["received", "partial"] } }). Use it when hand-authoring a blueprint; the structured design path uses conditions instead. Wins over conditions when both are given.

BlueprintNavItem

Properties

PropertyTypeRequiredDescription
typeEnum<'object' | 'dashboard'>optional (default: "object")What this nav entry opens
targetstring✅Object or dashboard machine name to surface (snake_case)
labelstringoptionalNav entry label. Optional: absent ⇒ the entry inherits the CURRENT label of what it opens at render time (a renamed target shows its new name); present ⇒ rendered verbatim, so never copy the target's label in as a default.
iconstringoptionalLucide icon name for the nav entry
viewNamestringoptionalFor type:"object" only — the views[].name this entry opens (e.g. "ticket_status_board"). Omit for the object's default list. SET it whenever this blueprint authors a kanban/calendar/gallery/gantt view the menu should reach: give the object ONE entry per view (a 「工单列表」 entry with no viewName plus a 「工单看板」 entry with viewName:"ticket_status_board"). Without it every entry on the same target opens the SAME default list, and a label/icon saying otherwise is decoration.

BlueprintObject

Properties

PropertyTypeRequiredDescription
namestring✅Object machine name (snake_case)
labelstringoptionalHuman-readable singular label
descriptionstringoptionalWhat this object represents
fields{ name: string; label?: string; type: Enum<'text' | 'textarea' | 'email' | 'url' | 'phone' | 'password' | 'secret' | …>; required?: boolean; … }[]✅Fields to create on the object
sharingModelEnum<'private' | 'public_read' | 'public_read_write' | 'controlled_by_parent'>optionalOrg-Wide Default record visibility (OWD) for INTERNAL users — the deliberate sharing choice for this object (ADR-0090). Canonical four only: private (owner-only) | public_read (everyone reads, owner writes) | public_read_write (everyone reads+writes) | controlled_by_parent (derived from the master record — ONLY for an object whose fields include a master_detail reference). SET it when the user's description implies a visibility intent — personal/private data (HR, 绩效, salary, 个人隐私) → "private"; shared reference data everyone edits → "public_read_write". Omit to accept the platform's deterministic default (business object → public_read_write; master-detail child → controlled_by_parent) — omitting on privacy-sensitive data silently over-shares it.
nameFieldstringoptionalThe 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. a formula "record.order_no + ' · ' + record.customer.name" — a lookup's name is read one hop through it, record.<lookup>.<name field>). A formula title is computed on read and stored nowhere: it is shown everywhere, but a list cannot sort by it and search does not scan it. Omitting it lets the platform auto-pick a text field, but declaring it is strongly preferred.
stageFieldstringoptionalThe lifecycle stage field (ADR-0085) — which select (or radio) field of THIS object holds the ordered steps a record moves through (a deal's stage, a ticket's status), drawn as the record path. snake_case, naming one of this object's own fields. The object schema refuses the object unless the field stageField names is a single-value select or radio whose inline options EACH declare kind: "open" for a step on the way, "won" for the successful end (a deal's Closed Won, a task's Done, a case's Resolved), "lost" for the unsuccessful end (Closed Lost, Cancelled, Unqualified). Naming a multiselect / checkboxes / tags field that carries options is refused too: a record stands at one stage. SET it whenever the object has such a status/stage field, and give every one of that field's options its kind. Omitting it leaves stage detection to a guess from field names (status / stage / state / phase).

Nested Shape: BlueprintObject.fields[number]

PropertyTypeRequiredDescription
namestring✅Field machine name (snake_case)
labelstringoptionalHuman-readable field label
typeEnum<'text' | 'textarea' | 'email' | 'url' | 'phone' | 'password' | 'secret' | …>✅Field data type
requiredbooleanoptionalWhether the field is required
referencestringoptionalTarget object name for lookup / master_detail relationship fields
options{ label: string; value: string; kind?: Enum<'open' | 'won' | 'lost'> }[]optionalChoices for select / multiselect / radio fields
summaryOperations{ object: string; function: Enum<'count' | 'sum' | 'avg' | 'min' | 'max'>; field?: string; relationshipField?: string; … }optionalREQUIRED when type is "summary" (a roll-up of child records: 任务总数 / 报名人数 / 合计金额 / 已完成任务数). Names the child object, the aggregation, and — for a qualified count/sum — the condition. A "summary" field without it materializes runtime-dead.
expressionstringoptionalREQUIRED when type is "formula" — the CEL body the field computes, e.g. "record.quantity * record.unit_price", or "record.order_no + ' · ' + record.customer.name" for a composed title. A formula reads a lookup / master_detail field's related record ONE hop through it — record.<lookup>.<field>, as record.customer.name above; the bare record.customer is the stored id, and a second hop (record.customer.owner.name) is refused at build. A "formula" field without it materializes runtime-dead: the engine builds its formula plan only from fields that HAVE an expression, so the field reads null everywhere, forever. Same failure shape as a "summary" with no summaryOperations. Note nameField on the object recommends a formula for numbered entities (invoice/ticket) — that formula needs THIS key, or the record title is blank on every card, lookup chip and breadcrumb.
defaultValueboolean | number | stringoptionalThe built field's default: the value a new record gets when it is created without one, carried into the object field as its defaultValue and stored as written. It must fit type, and only these types take one: "boolean" / "toggle" → true or false; "number" / "currency" / "percent" / "rating" / "slider" / "progress" → a number; "text" / "textarea" / "email" / "url" / "phone" / "markdown" / "html" / "richtext" / "code" / "color" → a string; "time" → a time of day, "HH:MM"; "select" / "radio" → the value of one of the field's own options, never its label. Every other type is refused by name: a date is fixed at design time, a reference or file names no record yet, a multi-value field stores a list, a formula / summary / autonumber is computed, and a credential, signature or structured value has no one value right for every record. A yes/no flag (是否完成 / 已付款 / is_active) is a "boolean" field that is never required (omit required or set it false) and carries defaultValue false: a required flag refuses the unchecked switch, and a flag with no default is empty, not false, on every record created without it, so a filter on false misses those records. Omit it for a field with no default.

BlueprintSeed

Properties

PropertyTypeRequiredDescription
objectstring✅Target object name (snake_case)
recordsRecord<string, any>[]✅Rows to seed

BlueprintSummaryOperations

Properties

PropertyTypeRequiredDescription
objectstring✅The CHILD object whose records are aggregated (snake_case). It must carry a lookup / master_detail field pointing back at this parent, or the roll-up never computes.
functionEnum<'count' | 'sum' | 'avg' | 'min' | 'max'>✅Aggregation: "数量 / 个数 / 计数" → count; "合计 / 总额 / 累计" → sum; "平均" → avg
fieldstringoptionalNumeric field on the CHILD object to aggregate. Ignored for "count" (pass "id" or omit it).
relationshipFieldstringoptionalThe child FK field pointing back at this parent. Auto-detected from the child's lookup / master_detail; set it only when the child has more than one reference to this parent.
conditions{ field: string; op: Enum<'lt' | 'lte' | 'gt' | 'gte' | 'eq' | 'ne'>; value: number | string | boolean }[]optionalCONDITIONAL roll-up: aggregate only the child rows matching these comparisons (ANDed). REQUIRED whenever the field name carries a qualifier — "已完成任务数 / 已收货金额 / 待处理工单数", any 已X / 未X / <某状态>的 count-or-sum → e.g. [{ field: "status", op: "eq", value: "completed" }]. WITHOUT it the roll-up silently counts EVERY child and reports a plausible-looking WRONG number, which is worse than a visible 0.
filteranyoptionalThe same predicate as a canonical query filter map (e.g. { status: "completed" }, { status: { $in: ["received", "partial"] } }). Use it when hand-authoring a blueprint; the structured design path uses conditions instead. Wins over conditions when both are given.

Nested Shape: BlueprintSummaryOperations.conditions[number]

PropertyTypeRequiredDescription
fieldstring✅Field on the target object to filter by (e.g. "stock_quantity", "status")
opEnum<'lt' | 'lte' | 'gt' | 'gte' | 'eq' | 'ne'>✅Comparison operator
valuenumber | string | boolean✅Comparison value — for a select field use its option VALUE, never its label (e.g. "completed", not "已完成")

BlueprintView

Properties

PropertyTypeRequiredDescription
objectstring✅Object this view displays (snake_case)
namestring✅View machine name (snake_case)
labelstringoptionalHuman-readable view label
typeEnum<'list' | 'form' | 'kanban' | 'calendar' | 'gallery' | 'gantt'>optional (default: "list")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".
columnsstring[]optionalField 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.
groupBystringoptionalREQUIRED 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).
filters{ field: string; operator: Enum<'equals' | 'not_equals' | 'contains' | 'not_contains' | 'icontains' | …>; value?: string | number | boolean | null | (string | number)[] }[]optionalWhich records this view shows: the list-view filter rules [{ field, operator, value }] the built view carries, ANDed. REQUIRED whenever the view's name or label states a condition — an 「overdue / 逾期」, 「my open / 我的未完成」, 「待审批」 or 「本月」 view MUST carry the rules that make its name true, e.g. overdue → [{ field: "due_date", operator: "less_than", value: "{today}" }, { field: "status", operator: "not_equals", value: "completed" }]; my open → [{ field: "owner", operator: "equals", value: "{current_user_id}" }, { field: "status", operator: "equals", value: "open" }]. WITHOUT it the view shows EVERY record under a name that promises a subset. For a select field compare its option VALUE, never its label. Omit for a view that genuinely spans every record.
sort{ field: string; order: Enum<'asc' | 'desc'> }[]optionalDefault record order: [{ field, order }] with order "asc" or "desc"; the first entry sorts first (e.g. an overdue list → [{ field: "due_date", order: "asc" }]). Omit for the platform default order.
startDateFieldstringoptionalFor type:"calendar" only: the date or datetime field of THIS view's object that places each record on the calendar (e.g. "interview_date", "due_date"), carried into the built view as calendar.startDateField. snake_case, naming one of the object's own fields. SET it on every calendar view; without it the builder binds a date field of its own choosing, which may not be the one meant. Ignored on the other view types (a gantt view takes its dates from columns, start before end).

Nested Shape: BlueprintView.filters[number]

View filter rule

PropertyTypeRequiredDescription
fieldstring✅Field name to filter on
operatorEnum<'equals' | 'not_equals' | 'contains' | 'not_contains' | 'icontains' | …>✅Filter operator
valuestring | number | boolean | null | (string | number)[]optionalFilter value. The accepted SHAPE depends on the operator: in / not_in take an array (any length, including []), between takes exactly [min, max], every other operator takes a scalar. The unary operators (is_empty / is_not_empty / is_null / is_not_null) take their direction from the operator name and ignore this key. One operator bounds the VALUE as well as the shape: icontains takes a NON-EMPTY STRING, the comparand the Filter Protocol conformance table declares for it — an empty comparand constrains nothing and a non-string one would answer a query nobody wrote, and both are refused at the query path too.

Nested Shape: BlueprintView.sort[number]

Sort field and direction pair

PropertyTypeRequiredDescription
fieldstring✅Field name to sort by
orderEnum<'asc' | 'desc'>✅Sort direction

BlueprintWidgetCondition

Properties

PropertyTypeRequiredDescription
fieldstring✅Field on the target object to filter by (e.g. "stock_quantity", "status")
opEnum<'lt' | 'lte' | 'gt' | 'gte' | 'eq' | 'ne'>✅Comparison operator
valuenumber | string | boolean✅Comparison value — for a select field use its option VALUE, never its label (e.g. "completed", not "已完成")

SolutionBlueprint

Properties

PropertyTypeRequiredDescription
summarystringoptionalOne-line description of the proposed solution
assumptionsstring[]optional (default: [])Design assumptions made from the underspecified goal
questionsstring[]optionalAt most 1-2 structure-deciding questions to confirm before building
objects{ name: string; label?: string; description?: string; fields: object[]; … }[]✅Objects (tables) to create
views{ object: string; name: string; label?: string; type?: Enum<'list' | 'form' | 'kanban' | 'calendar' | 'gallery' | 'gantt'>; … }[]optionalViews to create
dashboards{ name: string; label?: string; widgets?: object[] }[]optionalDashboards to create
app{ name: string; label?: string; icon?: string; nav?: object[] }optionalThe navigation shell (app) that surfaces the created objects/dashboards to end users
seedData{ object: string; records: Record<string, any>[] }[]optionalSuggested seed data (reported, not auto-applied in Phase C)

Nested Shape: SolutionBlueprint.objects[number]

PropertyTypeRequiredDescription
namestring✅Object machine name (snake_case)
labelstringoptionalHuman-readable singular label
descriptionstringoptionalWhat this object represents
fields{ name: string; label?: string; type: Enum<'text' | 'textarea' | 'email' | 'url' | 'phone' | 'password' | 'secret' | …>; required?: boolean; … }[]✅Fields to create on the object
sharingModelEnum<'private' | 'public_read' | 'public_read_write' | 'controlled_by_parent'>optionalOrg-Wide Default record visibility (OWD) for INTERNAL users — the deliberate sharing choice for this object (ADR-0090). Canonical four only: private (owner-only) | public_read (everyone reads, owner writes) | public_read_write (everyone reads+writes) | controlled_by_parent (derived from the master record — ONLY for an object whose fields include a master_detail reference). SET it when the user's description implies a visibility intent — personal/private data (HR, 绩效, salary, 个人隐私) → "private"; shared reference data everyone edits → "public_read_write". Omit to accept the platform's deterministic default (business object → public_read_write; master-detail child → controlled_by_parent) — omitting on privacy-sensitive data silently over-shares it.
nameFieldstringoptionalThe 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. a formula "record.order_no + ' · ' + record.customer.name" — a lookup's name is read one hop through it, record.<lookup>.<name field>). A formula title is computed on read and stored nowhere: it is shown everywhere, but a list cannot sort by it and search does not scan it. Omitting it lets the platform auto-pick a text field, but declaring it is strongly preferred.
stageFieldstringoptionalThe lifecycle stage field (ADR-0085) — which select (or radio) field of THIS object holds the ordered steps a record moves through (a deal's stage, a ticket's status), drawn as the record path. snake_case, naming one of this object's own fields. The object schema refuses the object unless the field stageField names is a single-value select or radio whose inline options EACH declare kind: "open" for a step on the way, "won" for the successful end (a deal's Closed Won, a task's Done, a case's Resolved), "lost" for the unsuccessful end (Closed Lost, Cancelled, Unqualified). Naming a multiselect / checkboxes / tags field that carries options is refused too: a record stands at one stage. SET it whenever the object has such a status/stage field, and give every one of that field's options its kind. Omitting it leaves stage detection to a guess from field names (status / stage / state / phase).

Nested Shape: SolutionBlueprint.views[number]

PropertyTypeRequiredDescription
objectstring✅Object this view displays (snake_case)
namestring✅View machine name (snake_case)
labelstringoptionalHuman-readable view label
typeEnum<'list' | 'form' | 'kanban' | 'calendar' | 'gallery' | 'gantt'>optional (default: "list")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".
columnsstring[]optionalField 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.
groupBystringoptionalREQUIRED 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).
filters{ field: string; operator: Enum<'equals' | 'not_equals' | 'contains' | 'not_contains' | 'icontains' | …>; value?: string | number | boolean | null | (string | number)[] }[]optionalWhich records this view shows: the list-view filter rules [{ field, operator, value }] the built view carries, ANDed. REQUIRED whenever the view's name or label states a condition — an 「overdue / 逾期」, 「my open / 我的未完成」, 「待审批」 or 「本月」 view MUST carry the rules that make its name true, e.g. overdue → [{ field: "due_date", operator: "less_than", value: "{today}" }, { field: "status", operator: "not_equals", value: "completed" }]; my open → [{ field: "owner", operator: "equals", value: "{current_user_id}" }, { field: "status", operator: "equals", value: "open" }]. WITHOUT it the view shows EVERY record under a name that promises a subset. For a select field compare its option VALUE, never its label. Omit for a view that genuinely spans every record.
sort{ field: string; order: Enum<'asc' | 'desc'> }[]optionalDefault record order: [{ field, order }] with order "asc" or "desc"; the first entry sorts first (e.g. an overdue list → [{ field: "due_date", order: "asc" }]). Omit for the platform default order.
startDateFieldstringoptionalFor type:"calendar" only: the date or datetime field of THIS view's object that places each record on the calendar (e.g. "interview_date", "due_date"), carried into the built view as calendar.startDateField. snake_case, naming one of the object's own fields. SET it on every calendar view; without it the builder binds a date field of its own choosing, which may not be the one meant. Ignored on the other view types (a gantt view takes its dates from columns, start before end).

Nested Shape: SolutionBlueprint.dashboards[number]

PropertyTypeRequiredDescription
namestring✅Dashboard machine name (snake_case)
labelstringoptionalHuman-readable dashboard label
widgets{ id: string; title?: string; object?: string; chart?: Enum<'metric' | 'bar' | 'line' | 'pie' | 'table'>; … }[]optionalWidgets to place on the dashboard

Nested Shape: SolutionBlueprint.app

PropertyTypeRequiredDescription
namestring✅App machine name (snake_case)
labelstringoptionalApp display label
iconstringoptionalLucide icon for the App Launcher
nav{ type?: Enum<'object' | 'dashboard'>; target: string; label?: string; icon?: string; … }[]optionalNavigation entries; omit to auto-surface every created object and dashboard

Nested Shape: SolutionBlueprint.seedData[number]

PropertyTypeRequiredDescription
objectstring✅Target object name (snake_case)
recordsRecord<string, any>[]✅Rows to seed

SolutionBlueprintStrict

Properties

PropertyTypeRequiredDescription
summarystring✅One-line description of the proposed solution
assumptionsstring[]✅Design assumptions made from the underspecified goal
questionsstring[] | null✅At most 1-2 structure-deciding questions to confirm before building, or null
objects{ name: string; label: string | null; description: string | null; fields: object[]; … }[]✅Objects (tables) to create
views{ object: string; name: string; label: string | null; type: Enum<'list' | 'form' | 'kanban' | 'calendar' | 'gallery' | 'gantt'> | null; … }[] | null✅Views to create, or null
dashboards{ name: string; label: string | null; widgets: object[] | null }[] | null✅Dashboards to create, or null
app{ name: string; label: string | null; icon: string | null; nav: object[] | null } | null✅The navigation shell (app) that surfaces the created objects/dashboards, or null

Nested Shape: SolutionBlueprintStrict.objects[number]

PropertyTypeRequiredDescription
namestring✅Object machine name (snake_case)
labelstring | null✅Human-readable singular label, or null
descriptionstring | null✅What this object represents, or null
fields{ name: string; label: string | null; type: Enum<'text' | 'textarea' | 'email' | 'url' | 'phone' | 'password' | 'secret' | …>; required: boolean | null; … }[]✅Fields to create on the object
sharingModelEnum<'private' | 'public_read' | 'public_read_write' | 'controlled_by_parent'> | null✅Org-Wide Default record visibility (OWD) for INTERNAL users (ADR-0090), or null to accept the platform default (business object → public_read_write; master-detail child → controlled_by_parent). SET it when the user's description implies a visibility intent: personal/private data (HR, 绩效, salary, 个人隐私) → "private" (owner-only); "public_read" = everyone reads, owner writes; "public_read_write" = everyone reads+writes; "controlled_by_parent" ONLY for an object with a master_detail reference field. Null on privacy-sensitive data silently over-shares it.
nameFieldstring | null✅The record title field — which field holds the human-readable name shown on cards, lookup chips, breadcrumbs and search (ADR-0079), or null to let the platform auto-pick a text field. Set it to the object's text label field (e.g. "product_name") — snake_case. For a numbered entity (invoice/ticket), set it to a formula field that composes number + name (e.g. a formula "record.order_no + ' · ' + record.customer.name" — a lookup's name is read one hop through it, record.<lookup>.<name field>). A formula title is computed on read and stored nowhere: it is shown everywhere, but a list cannot sort by it and search does not scan it. Declaring it is strongly preferred over null.
stageFieldstring | null✅The lifecycle stage field (ADR-0085) — which select (or radio) field of THIS object holds the ordered steps a record moves through (a deal's stage, a ticket's status), drawn as the record path — or null. snake_case, naming one of this object's own fields. The object schema refuses the object unless the field stageField names is a single-value select or radio whose inline options EACH declare kind: "open" for a step on the way, "won" for the successful end (a deal's Closed Won, a task's Done, a case's Resolved), "lost" for the unsuccessful end (Closed Lost, Cancelled, Unqualified). Naming a multiselect / checkboxes / tags field that carries options is refused too: a record stands at one stage. SET it whenever the object has such a status/stage field, and give every one of that field's options a non-null kind. Null leaves stage detection to a guess from field names (status / stage / state / phase).

Nested Shape: SolutionBlueprintStrict.views[number]

PropertyTypeRequiredDescription
objectstring✅Object this view displays (snake_case)
namestring✅View machine name (snake_case)
labelstring | null✅Human-readable view label, or null
typeEnum<'list' | 'form' | 'kanban' | 'calendar' | 'gallery' | 'gantt'> | null✅View kind, or null for list. "gallery" = visual card/cover browse (画廊/相册/卡片墙/封面/海报, or an object with an image/avatar/file field); "gantt" = timeline/schedule (甘特图/时间线/排期, object with BOTH a start and an end date field); "kanban" = board grouped by a status/select field; "calendar" = single-date schedule; "form" = record editor.
columnsstring[] | null✅Field names shown as columns, or null. For a gallery, INCLUDE the image/avatar/file field (becomes the card cover); for a gantt, INCLUDE the start date column before the end date column.
groupBystring | null✅REQUIRED for kanban: the select/status field whose options become the board columns (e.g. "stage"). Optional for gantt (groups leaf tasks). Null for list/form/calendar/gallery.
filters{ field: string; operator: Enum<'equals' | 'not_equals' | 'contains' | 'not_contains' | 'icontains' | …>; value: string | number | boolean | (string | number)[] | null }[] | null✅Which records this view shows: list-view filter rules [{field, operator, value}], ANDed, or null for a view over EVERY record. REQUIRED whenever the view's name or label states a condition — an 「overdue / 逾期」, 「my open / 我的未完成」, 「待审批」 or 「本月」 view MUST carry the rules that make its name true, e.g. overdue → [{field:"due_date",operator:"less_than",value:"{today}"},{field:"status",operator:"not_equals",value:"completed"}]; my open → [{field:"owner",operator:"equals",value:"{current_user_id}"},{field:"status",operator:"equals",value:"open"}]. Null under such a name ships a view that shows every record while its name promises a subset.
sort{ field: string; order: Enum<'asc' | 'desc'> }[] | null✅Default record order: [{field, order}] with order "asc" or "desc"; the first entry sorts first (e.g. an overdue list → [{field:"due_date",order:"asc"}]), or null for the platform default order.
startDateFieldstring | null✅For type:"calendar" only: the date or datetime field of THIS view's object that places each record on the calendar (e.g. "interview_date", "due_date"), carried into the built view as calendar.startDateField. snake_case, naming one of the object's own fields. SET it on every calendar view; without it the builder binds a date field of its own choosing, which may not be the one meant. Ignored on the other view types (a gantt view takes its dates from columns, start before end). Null on every view that is not a calendar.

Nested Shape: SolutionBlueprintStrict.dashboards[number]

PropertyTypeRequiredDescription
namestring✅Dashboard machine name (snake_case)
labelstring | null✅Human-readable dashboard label, or null
widgets{ id: string; title: string | null; object: string | null; chart: Enum<'metric' | 'bar' | 'line' | 'pie' | 'table'> | null; … }[] | null✅Widgets to place on the dashboard, or null

Nested Shape: SolutionBlueprintStrict.app

PropertyTypeRequiredDescription
namestring✅App machine name (snake_case)
labelstring | null✅App display label, or null
iconstring | null✅Lucide icon for the App Launcher, or null
nav{ type: Enum<'object' | 'dashboard'>; target: string; label: string | null; icon: string | null; … }[] | null✅Navigation entries; null to auto-surface every created object and dashboard

On this page