Schema based UI
How to define model specs in a realm.
See Model System for the concept overview and the blong-model skill for agent assistance with model development.
Folder Structure
Each realm that uses the model system organises its models and fixture data in a dedicated folder.
The conventional structure (as seen in demo/blong-marine/) is:
marine/
meta/
model/
marineCoralModel.ts ← IModelSpec handler for coral entity
marineFamilyModel.ts
marineHabitatModel.ts
fixture/
marineFixture.ts ← Fixture data handler for Storybook/tests
orchestrator/
marine.ts ← Forwarding orchestrator (dispatches to backend)
browser.ts ← Realm entry point (auto-discovers meta/ folder)
The model files are discovered by the portal orchestrator and mock adapter via the .model handler
kind (set by the model() factory). The fixture file is discovered via the .fixture handler kind.
Defining a ModelSpec
Model specs use the model() factory from @feasibleone/blong. The factory wraps an async handler
function whose name follows the pattern {subject}{Object}Model.
// marine/meta/model/marineCoralModel.ts
import {model} from '@feasibleone/blong';
export default model(
() =>
async function marineCoralModel() {
return {
subject: 'marine',
object: 'coral',
objectTitle: 'Coral', // defaults to capitalized 'object'
keyField: 'coralId', // defaults to '${object}Id'
// Browser-side schema overlay (merged with runtime schema from {subject}.{object}.schema handler)
schema: {
properties: {
coral: {
properties: {
coralId: {},
coralName: {title: 'Name', filter: true, sort: true},
familyId: {
title: 'Family',
widget: {type: 'dropdown', dropdown: 'marine.family'},
},
habitatId: {
title: 'Habitat',
widget: {type: 'dropdown', dropdown: 'marine.habitat'},
},
maxDepth: {title: 'Max Depth (m)'},
colorPattern: {title: 'Color Pattern'},
discovered: {widget: {type: 'date'}},
description: {widget: {type: 'textArea'}},
},
// Override table widget options for the browse panel
widget: {
columns: ['coralName', 'familyId', 'maxDepth'],
},
},
},
},
// Named groups of fields for the editor form
cards: {
browse: {
label: 'Coral',
widgets: ['coral'],
},
edit: {
label: 'Coral Details',
widgets: [
'coral.coralName',
'coral.familyId',
'coral.habitatId',
'coral.maxDepth',
'coral.colorPattern',
'coral.discovered',
'coral.description',
],
},
},
// How cards are arranged on the edit page
layouts: {
edit: ['edit'],
},
// Browse page toolbar buttons
browser: {
title: 'Coral List',
icon: 'pi pi-star',
toolbar: [
{
label: 'Create',
icon: 'pi pi-plus',
action: 'component/marine.coral.new',
permission: 'marine.coral.add',
},
{
label: 'Edit',
icon: 'pi pi-pencil',
enabled: 'current' as const,
method: 'component/marine.coral.open',
params: '${current}',
},
{
label: 'Delete',
icon: 'pi pi-trash',
enabled: 'selected' as const,
confirm: 'Delete selected record?',
method: 'marine.coral.remove',
params: {coralId: '${coralId}'},
},
],
},
};
},
);
Menu Placement
The aggregator builds the menubar from the specs, so a realm with a handful of models needs no menu
code at all: each browse page joins the group named by subjectTitle (the capitalized subject by
default). A realm with twenty pages says where each one belongs instead of letting one group grow
past the height of a laptop screen:
classifier: true, // reference data a form picks from
menu: {group: 'Registry'}, // a flat group of its own
menu: {group: 'Registry', order: 3}, // …at a chosen position in it
menu: {root: 'Reference', group: 'Sport'}, // nested two levels deep
menu: {title: 'Athletes', icon: 'pi pi-user'}, // leaf label and icon
menu: {hidden: true}, // no entry; still reachable by method
classifier: true is the flag for dropdown sources — sport, discipline, area, category, cycle.
Every realm's classifiers land in one Classifiers group with a submenu per realm, so the list a
form picks from is found in one place and the realm's own group holds the pages people open all day.
A group title is the merge key: two realms that both declare Registry contribute to one group, and
the ids the portal derives from the titles stay language independent. subjectTitle renames a
subject's group (Translations for the core dictionary pages).
order fixes a page's position inside its group — lowest first. Pages that name no order come after
the ordered ones, alphabetically, so a group where nothing is ordered is simply sorted by label; the
comparison uses the English label, because that is what the model declares.
A realm whose menu is written by hand configures ui.portal.portal.menu, which adds groups to the
generated ones, and sets menuMode: 'replace' when it should be the whole menubar.
Fixture Data for Storybook and Tests
The mock adapter auto-generates all CRUD mock handlers from the handlers whose group name ends in
.model / .fixture. Create a fixture handler with the ordinary handler() factory from
@feasibleone/blong:
// marine/meta/fixture/marineFixture.ts
import {handler} from '@feasibleone/blong';
import marineYaml from '../../data/marine.yaml?raw';
export default handler(
({lib: {yaml}}) =>
async function marineFixture() {
return yaml.parse(marineYaml);
},
);
Not the
fixture()factory.fixture()from@feasibleone/blongdescribes mock OpenAPI documents (a{subjects, dropdowns}shape), so its type rejects the sample-rows object below.
The fixture handler must be named {subject}Fixture and return an object keyed by
'{subject}.{object}' with arrays of item objects. The mock adapter calls
blong.handler['{subject}Fixture']({}, {}) to load the data.
For inline fixture data (small datasets or when YAML is overkill):
import {handler} from '@feasibleone/blong';
export default handler(
() =>
async function marineFixture() {
return {
'marine.coral': [
{coralId: 1, coralName: 'Brain Coral', familyId: 1, maxDepth: 40},
{coralId: 2, coralName: 'Staghorn Coral', familyId: 2, maxDepth: 25},
],
'marine.family': [
{familyId: 1, familyName: 'Acroporidae'},
{familyId: 2, familyName: 'Faviidae'},
],
};
},
);
The realm's browser.ts must glob the fixture folder next to the models
(import.meta.glob(['./meta/model/**/*.ts', './meta/fixture/**/*.ts', …])). The browser platform
loads a realm only through the children it is given — it does not scan layer folders the way the
server does — so a fixture that browser.ts does not glob never reaches the mock adapter and every
story renders empty.
The mock generates the following handlers automatically from each model + fixture:
{subject}.{object}.find,.get,.add,.edit,.remove,.report{subject}.{object}.schema— returns{}{subject}.dropdown.list— synthesises from fixture data
Schema Overlay Reference
Key field properties available in the schema overlay:
| Property | Type | Effect |
|---|---|---|
title | string | Override field label in forms and column headers |
filter | boolean | Show field in the browse filter bar |
sort | boolean | Make column sortable in Explorer |
required | boolean | Mark field required (client-side validation) |
default | any | Default value for new entity forms |
widget | IWidgetOverride | Widget type and widget-specific options |
Key widget types:
widget.type | PrimeReact component | Extra widget props |
|---|---|---|
dropdown | Dropdown | dropdown: 'subject.name' |
multiSelect | MultiSelect | dropdown: 'subject.name' |
selectTable | DataTable (select) | dropdown: 'subject.name' |
date | Calendar | |
dateTime | Calendar (showTime) | |
textArea | InputTextarea | |
boolean | Checkbox | |
integer | InputNumber (no decimals) | |
number | InputNumber | |
currency | InputNumber (currency) | currency: 'USD' |
select | SelectButton | options: [{value, label}] |
table | DataTable (editable) | widgets: ['col1', 'col2'] |
Browse Page Configuration
browser: {
title: 'Corals', // menu item and tab title
icon: 'pi pi-star', // PrimeIcon class
permission: {
browse: 'marine.coral.browse',
add: 'marine.coral.new',
edit: 'marine.coral.open',
delete: 'marine.coral.remove',
},
filter: {isActive: true}, // default filter on page open (optional)
create: [{ // "Create" button override (optional)
title: 'New Coral',
type: 'default',
permission: 'marine.coral.new',
}],
}
What the configuration above produces, captured from demo/blong-marine:



All three are the same generated page: the portal menu and tab, the toolbar, a navigator pane, the
table with its search box and paging, and the detail pane that fills in when a row is selected. The
Coral picture is filtered to Staghorn by the spec used in the test, which is why it shows one row;
Species and Habitat differ only in their IModelSpec. Nothing beyond the spec above draws any of
it.
The other half of a model page is the one the pictures do not show — a form nobody wrote either. The
create block in the spec above is what the toolbar's Create button runs, and this is the page it
opens, live:
The images are written by demo/blong-marine/test/docs.play.ts, which opens each page and captures
it only under BLONG_CAPTURE_DOCS=1; the blong-docs skill documents the conventions for
publishing one.
Deletion
deletion configures what the browse page's Delete button does — prompt (the default), cascade,
block or deactivate — and the generated toolbar carries it, so nothing is repeated per button:
deletion: {mode: 'block'}, // refuse, naming the records that still refer to this one
deletion: {mode: 'cascade'}, // take them with it, without asking
deletion: {mode: 'deactivate', flag: {field: 'areaStatus', value: 'inactive'}},
See the deletion pattern for the full reference, what a cascade does to the foreign keys and how to test each mode.
Method Name Overrides
By default, the model system infers method names from {subject}.{object}.{verb}. To override:
methods: {
find: 'marine.coral.search', // non-standard list method name
report: 'marine.report.coral', // cross-namespace report
}
Adding a Report Page
report: {
title: 'Coral Report',
permission: 'marine.coral.report',
}
The report page is only registered when this is present. What that produces, beside the browse page it is reached from — a Run Report toolbar button, a params card, and a Results table:

The rows in the picture are the demo database as the suite's own regression specs left it, which is also the honest illustration of one limitation: the params card is not editable, so a generated report cannot be narrowed from its own filter fields yet.