[data-reveal]{opacity:1!important;transform:none!important}
AntelopeJS DMS
DocumentationSpec file

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

text
<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 of spec.json over the built-in block types.
  • mockup-example/spec.json, a two-page example with no issue. GET /api/mockup/example answers it.

Example

mockups/order-desk/spec.json json
{
  "$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.

FieldMeaning
$schemaOptional. Points an editor at the JSON Schema.
versionAlways 1.
titleOptional. The title the Mockups page and the viewer show.
sourceOptional. Who wrote the mockup: chat, claude-code or codex.
builtOptional. 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.
dataOptional. The external connection the app reads, as { connection, access? }. See Connection access.
categoriesOptional. 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.
sidebarOptional. Sketched sidebar widgets, as { widgets }. See Sidebar widgets.
modulesOptional. The DMS modules the app needs, as a list of ids from the module store catalog, such as ["mailing", "media"]. See Modules.
pages0 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

FieldMeaning
idMatches ^[a-z0-9][a-z0-9-]{0,63}$. Unique in the spec.
titleThe page's display name, drawn in its page header.
categoryOptional. The id of the section the page is listed under. Without it, the page is in the default Pages section.
menuOptional. false keeps the page out of the sidebar, as for a detail page that another page opens. Defaults to true.
parentOptional. The id of the page this one is a sub-page of. See Sub-pages.
routeOptional. A route parameter such as :id. The page then shows one row of its parent's rows. It needs a parent.
iconOptional. The page's icon, such as i-ph-shopping-cart. Without it, the header draws i-ph-file.
descriptionOptional. Drawn under the title in the page header.
headerActionsOptional. 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.themelight or dark.
options.localeA locale the dashboard knows, such as fr-FR.
options.paddingPads the blocks off the edges of the frame. Defaults to true.
fixturesThe data the page's blocks read. Each key matches ^[A-Za-z0-9_-]{1,64}$ and holds any JSON value, or a generated value.
liveRoutesOptional. The live route of each fixture key, such as { "sales": "/api/sales" }. See Live routes.
livePageSet on a page converted from a live page, and by the build on each page it built, as { ref, version }. See Live page mockups.
treeThe page's nodes, top to bottom. Absent or empty on a custom page.
customOptional. true draws the page as one sketch. See Custom pages.
html, css, height, statesThe 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.

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_spec names 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:

json
{ "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:

BlockRefused option
TableViewrowActions.add, edit, duplicate, delete, archive or restore turned on
TableViewarchiveMode: true
TableViewkanban.draggable: true
ResourceFormA 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:

ts
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 }>;
}
FieldMeaning
revisionGoes up by one each time the backend reads spec.json.
treeThe page's nodes, with fixture references replaced, controller blocks built and sketches checked.
realTreetree with each key of liveRoutes read from its live route. Present only when the page has liveRoutes.
generatedtrue on a page the compiler adds for a table's generated form page. See Controller blocks.
routeThe route parameter without its colon, and sample, the id of the row the page shows when no link names one.
linksThe ids of the pages this page links to, in spec order.
pathsThe spec pointer of each node, keyed by the layout path the renderer gives it.
issuesEmpty 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:

Terminal bash
pnpm --dir packages/dms mockup:schema

pnpm --dir packages/dms mockup:schema:check fails when the committed file is stale. CI runs it.