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.
Object or dashboard machine name to surface (snake_case)
label
string
optional
Nav 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.
icon
string
optional
Lucide icon name for the nav entry
viewName
string
optional
For 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.
The 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.
aggregate
Enum<'sum' | 'avg' | 'min' | 'max' | 'count'>
optional
How 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.
groupBy
string
optional
The 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.
Restrict 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.
REQUIRED 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.
expression
string
optional
REQUIRED 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.
defaultValue
boolean | number | string
optional
The 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.
The 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".
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.
Numeric field on the CHILD object to aggregate. Ignored for "count" (pass "id" or omit it).
relationshipField
string
optional
The 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.
CONDITIONAL 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.
filter
any
optional
The 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.
Object or dashboard machine name to surface (snake_case)
label
string
optional
Nav 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.
icon
string
optional
Lucide icon name for the nav entry
viewName
string
optional
For 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.
Org-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.
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. 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.
stageField
string
optional
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. 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).
REQUIRED 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.
expression
string
optional
REQUIRED 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.
defaultValue
boolean | number | string
optional
The 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.
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.
Numeric field on the CHILD object to aggregate. Ignored for "count" (pass "id" or omit it).
relationshipField
string
optional
The 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.
CONDITIONAL 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.
filter
any
optional
The 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.
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).
Which 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'> }[]
optional
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" }]). Omit for the platform default order.
startDateField
string
optional
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).
Filter 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.
Org-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.
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. 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.
stageField
string
optional
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. 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).
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).
Which 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'> }[]
optional
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" }]). Omit for the platform default order.
startDateField
string
optional
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).
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.
nameField
string | 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.
stageField
string | 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).
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.
columns
string[] | 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.
groupBy
string | 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.
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.
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.
startDateField
string | 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.