Spec file
Every field of a mockup's spec.json, the file layout of the mockups folder, and the compiled state the backend serves from the spec.
A mockup is one spec.json file. This page lists its fields. The nodes inside a page's tree have their own page, Nodes.
File layout
<project root>/
mockups/
<name>/
spec.json the spec
annotations.json the comments, written by the DMS
.antelope/
mockup-history/
<name>/
<n>.json one version of the spec, written by the DMS
The project root is the working directory of the backend process. <name> matches ^[a-z0-9][a-z0-9-]{0,63}$. The DMS ignores a folder whose name does not match, and a folder without spec.json. schema and example are reserved names.
@antelopejs/dms ships two files under node_modules/@antelopejs/dms/data/:
mockup-spec.schema.json, the JSON Schema ofspec.jsonover the built-in block types.mockup-example/spec.json, a two-page example with no issue.GET /api/mockup/exampleanswers it.
Example
{
"$schema": "../../node_modules/@antelopejs/dms/data/mockup-spec.schema.json",
"version": 1,
"title": "Order desk",
"categories": [{ "id": "sales", "title": "Sales", "icon": "i-ph-storefront" }],
"pages": [
{
"id": "orders",
"title": "Orders",
"category": "sales",
"icon": "i-ph-shopping-cart",
"description": "Every order, newest first",
"headerActions": [{ "label": "New order", "icon": "i-ph-plus", "color": "primary" }],
"fixtures": { "orders": [{ "_id": "o1", "customer": "Acme", "total": 120 }] },
"tree": [{ "type": "KpiCard", "options": { "title": "Revenue", "staticValue": 48210 } }]
}
]
}
Top-level fields
The envelope is strict. A key it does not list is an issue.
| Field | Meaning |
|---|---|
$schema | Optional. Points an editor at the JSON Schema. |
version | Always 1. |
title | Optional. The title the Mockups page and the viewer show. |
source | Optional. Who wrote the mockup: chat, claude-code or codex. |
built | Optional. Written by the build as { at, pages }. Without it, the mockup is a draft. at is an ISO 8601 date and time. pages lists 1 to 50 { path, title? }, where path is the route of a built page. |
data | Optional. The external connection the app reads, as { connection, access? }. See Connection access. |
categories | Optional. Up to 50 sidebar sections, as { id, title, icon? }, in menu order. id matches ^[a-z0-9][a-z0-9-]{0,63}$. The build makes each one a section with builder_create_category and section: true. |
sidebar | Optional. Sketched sidebar widgets, as { widgets }. See Sidebar widgets. |
modules | Optional. The DMS modules the app needs, as a list of ids from the module store catalog, such as ["mailing", "media"]. See Modules. |
pages | 0 to 50 pages. An empty list creates the mockup first, and the pages come later. |
The whole file nests at most 100 levels of objects and arrays.
Page fields
| Field | Meaning |
|---|---|
id | Matches ^[a-z0-9][a-z0-9-]{0,63}$. Unique in the spec. |
title | The page's display name, drawn in its page header. |
category | Optional. The id of the section the page is listed under. Without it, the page is in the default Pages section. |
menu | Optional. false keeps the page out of the sidebar, as for a detail page that another page opens. Defaults to true. |
parent | Optional. The id of the page this one is a sub-page of. See Sub-pages. |
route | Optional. A route parameter such as :id. The page then shows one row of its parent's rows. It needs a parent. |
icon | Optional. The page's icon, such as i-ph-shopping-cart. Without it, the header draws i-ph-file. |
description | Optional. Drawn under the title in the page header. |
headerActions | Optional. The buttons right of the title, as { label, icon?, color?, variant? }. color is one of neutral, primary, secondary, success, warning, error and info. variant is one of solid, outline, soft, ghost and link. What a button does is code, so the build wires it. |
options.theme | light or dark. |
options.locale | A locale the dashboard knows, such as fr-FR. |
options.padding | Pads the blocks off the edges of the frame. Defaults to true. |
fixtures | The data the page's blocks read. Each key matches ^[A-Za-z0-9_-]{1,64}$ and holds any JSON value, or a generated value. |
liveRoutes | Optional. The live route of each fixture key, such as { "sales": "/api/sales" }. See Live routes. |
livePage | Set on a page converted from a live page, and by the build on each page it built, as { ref, version }. See Live page mockups. |
tree | The page's nodes, top to bottom. Absent or empty on a custom page. |
custom | Optional. true draws the page as one sketch. See Custom pages. |
html, css, height, states | The sketch of a custom page. On any other page, each is an issue. |
A category, parent or link that names an id the spec lacks is an issue at that field. So is a chain of parents that leads back to the page.
Modules
modules lists the DMS modules the app needs by their catalog id: ai, api, automation, database, lang, mailing, marketing, media and saas. The ids are those of the catalog @antelopejs/dms ships in data/module-store/catalog.json.
{ "version": 1, "modules": ["mailing", "media"], "pages": [] }
- An id the catalog does not list is an issue at
/modules/<index>, which names the id and lists the known ones. - An id listed twice is an issue at the index of its second entry.
- The viewer shows the modules in a strip under its top bar, in every view, each with its icon and its name. The package shows on hover.
- Building the mockup installs each module with
ajs project modules add <package>.mockup_read_specnames the package of each module when it reads the whole spec or/modules.
Connection access
A mockup of an app over a client's database names the connection it reads, and the access the project gives the DMS on it:
{ "version": 1, "title": "CRM desk", "data": { "connection": "crm", "access": "read" }, "pages": [] }
connection is a connection id from config.externalConnections of the dms-database module. access is read or read-write, and defaults to read, as in dms-database.
With read, every option that writes rows is an issue, and a write of the spec is refused:
| Block | Refused option |
|---|---|
TableView | rowActions.add, edit, duplicate, delete, archive or restore turned on |
TableView | archiveMode: true |
TableView | kanban.draggable: true |
ResourceForm | A mode other than view |
rowActions.details and a ResourceForm in view mode are allowed. With read-write, or without data, nothing is restricted.
Compiled state
The backend compiles the spec against the block types registered now. GET /api/mockup/<name> and the state event answer the result as a MockupState:
interface PreviewNode {
type?: string;
componentName?: string;
options?: Record<string, unknown>;
children?: PreviewNode[];
id?: string;
slot?: string;
colSpan?: number;
}
interface MockupState {
name: string;
title?: string;
revision: number;
categories?: Array<{ id: string; title: string; icon?: string }>;
sidebar?: { widgets: Array<{ id: string; title?: string; html: string; css?: string; height: number }> };
modules?: Array<{ id: string; package: string; icon: string }>;
pages: Array<{
id: string;
title: string;
category?: string;
menu?: false;
custom?: true;
generated?: true;
parent?: string;
route?: { param: string; sample?: string };
links: string[];
icon?: string;
description?: string;
headerActions?: Array<{ label: string; icon?: string; color?: string; variant?: string }>;
options: { theme?: "light" | "dark"; locale?: string; padding?: boolean };
tree: PreviewNode[];
realTree?: PreviewNode[];
livePage?: { ref: string };
paths: Record<string, string>;
}>;
issues: Array<{ path: string; message: string }>;
}
| Field | Meaning |
|---|---|
revision | Goes up by one each time the backend reads spec.json. |
tree | The page's nodes, with fixture references replaced, controller blocks built and sketches checked. |
realTree | tree with each key of liveRoutes read from its live route. Present only when the page has liveRoutes. |
generated | true on a page the compiler adds for a table's generated form page. See Controller blocks. |
route | The route parameter without its colon, and sample, the id of the row the page shows when no link names one. |
links | The ids of the pages this page links to, in spec order. |
paths | The spec pointer of each node, keyed by the layout path the renderer gives it. |
issues | Empty when the spec is valid. Each path is a JSON pointer into spec.json, such as /pages/0/tree/1/options/title. "" names the whole file. |
The other page fields repeat the spec page's fields of the same name.
Compilation is lenient. A node with invalid options, or with an unknown type, stays in tree, and its issues are listed. When spec.json is not valid JSON, or its envelope breaks the rules, issues says why and pages keeps the last pages that compiled.
Regenerate the schema
The shipped schema covers the built-in block types. After a change to a block's options, regenerate it from the repository of @antelopejs/dms:
pnpm --dir packages/dms mockup:schema
pnpm --dir packages/dms mockup:schema:check fails when the committed file is stale. CI runs it.