docs/en/low-code/model-json.md
//[doc-seo]
{
"Description": "Define ABP Low-Code descriptor metadata and descriptor schemas for dynamic entities, pages, forms, filters, permissions, script endpoints, event handlers, background jobs, and workers."
}
Preview: The Low-Code System is currently in preview. The descriptor format is stable enough for evaluation and source control, but fields may change before general availability.
Low-code metadata is source-controlled as JSON descriptor files used by the Low-Code Designer and React runtime. Current generated projects keep descriptors as split files under _Dynamic; older projects may still contain an aggregate _Dynamic/model.json document. Use the Low-Code Designer for normal editing. Use this page when you need to review, generate, merge, or source-control the JSON metadata directly.
Generated low-code applications keep descriptor files in a _Dynamic folder under the application domain project. A typical project stores one JSON file per descriptor:
YourApp.Domain/
`-- _Dynamic/
|-- entities/
| `-- Acme.Campaigns.Campaign.json
|-- pages/
| `-- campaigns.json
|-- forms/
| `-- campaign-form.json
`-- permissions/
`-- Acme.Campaigns.json
Exact folders and file names are generated by the tooling for the descriptor type. Keep the whole _Dynamic folder and the generated initializer in source control. The low-code module discovers the descriptor metadata during application startup.
ABP publishes JSON Schema definitions for the descriptor objects that make up low-code metadata. These schemas are useful when you generate descriptors, review changes in source control, or want IDE validation for split descriptor files.
The schema files live in the ABP repository under schemas/low-code. Use the branch or tag that matches your ABP version.
The schema manifest is published at:
https://raw.githubusercontent.com/abpframework/abp/rel-10.5/schemas/low-code/manifest.json
For another version, replace rel-10.5 with the matching ABP branch or tag.
The manifest maps each descriptor collection to its descriptor schema:
| Descriptor collection | Descriptor schema |
|---|---|
enums | definitions/enum-descriptor.schema.json |
entities | definitions/entity-descriptor.schema.json |
endpoints | definitions/endpoint-descriptor.schema.json |
eventHandlers | definitions/script-event-handler-descriptor.schema.json |
backgroundJobs | definitions/script-background-job-descriptor.schema.json |
backgroundWorkers | definitions/script-background-worker-descriptor.schema.json |
pageGroups | definitions/page-group-descriptor.schema.json |
pages | definitions/page-descriptor.schema.json |
forms | definitions/form-descriptor.schema.json |
permissions | definitions/permission-descriptor.schema.json |
Use the descriptor schema directly when a descriptor is stored as its own JSON file. The descriptor object is the same shape used for one item inside the related descriptor collection.
{
"$schema": "https://raw.githubusercontent.com/abpframework/abp/rel-10.5/schemas/low-code/definitions/entity-descriptor.schema.json",
"name": "Acme.Campaigns.Campaign",
"displayName": "Campaigns",
"properties": []
}
For example, a file that stores one page descriptor can reference page-descriptor.schema.json, and a file that stores one form descriptor can reference form-descriptor.schema.json.
The published schemas validate individual descriptor objects, not an aggregate descriptor document. If you still maintain an aggregate _Dynamic/model.json, do not point it at entity-descriptor.schema.json, page-descriptor.schema.json, or another descriptor schema; those schemas expect one descriptor object, not the top-level arrays. For aggregate metadata, use the manifest table above as the section-level reference and validate each array item with its matching descriptor schema.
When descriptor metadata is viewed as an aggregate document, the logical sections are page/form centered. Entities define data shape; pages and forms define the React runtime UI.
{
"enums": [],
"entities": [],
"endpoints": [],
"eventHandlers": [],
"backgroundJobs": [],
"backgroundWorkers": [],
"pageGroups": [],
"pages": [],
"forms": [],
"permissions": []
}
| Section | Description |
|---|---|
enums | Reusable enum definitions |
entities | Dynamic entities, properties, relations, attachments, validations, and interceptors |
endpoints | JavaScript-backed custom HTTP endpoints |
eventHandlers | JavaScript handlers for distributed events |
backgroundJobs | Named JavaScript background job handlers |
backgroundWorkers | Scheduled JavaScript workers |
pageGroups | Menu folders used by runtime pages |
pages | React runtime page definitions, including data grids, kanban, calendar, gallery, form pages, and dashboards |
forms | Named form definitions referenced by pages |
permissions | Custom permission definitions referenced by pages and endpoints |
Define enums before properties that reference them:
{
"enums": [
{
"name": "Acme.Campaigns.CampaignStatus",
"values": [
{ "name": "Draft", "value": 0 },
{ "name": "Active", "value": 1 },
{ "name": "Paused", "value": 2 },
{ "name": "Completed", "value": 3 }
]
}
]
}
Use the enum from a property with type: "enum" and enumType:
{
"name": "Status",
"type": "enum",
"enumType": "Acme.Campaigns.CampaignStatus",
"defaultValue": "0"
}
Entities describe the persisted data model. UI is not configured with legacy property ui objects. Use page columns and filters, and named forms, for runtime UI behavior.
{
"name": "Acme.Campaigns.Campaign",
"displayName": "Campaigns",
"displayProperty": "Name",
"properties": [],
"crossFieldValidations": [],
"interceptors": []
}
| Field | Description |
|---|---|
name | Required stable full entity name, for example Acme.Campaigns.Campaign |
displayName | Default plural/screen label |
displayProperty | Property shown in lookups and foreign key display values |
parent | Parent entity name for child/detail entities |
attachments | Record-level attachment settings |
properties | Entity property definitions |
crossFieldValidations | Validation rules comparing two properties |
interceptors | Create, update, and delete lifecycle scripts |
{
"name": "Budget",
"type": "money",
"isRequired": true,
"isUnique": false,
"allowSetByClients": true,
"serverOnly": false,
"isMappedToDbField": true,
"validators": [
{ "type": "range", "minimum": 0, "maximum": 1000000 }
]
}
| Field | Description |
|---|---|
name | Required PascalCase property name |
type | Property type; omitted means string |
displayName | Default field label; pages/forms can override it |
enumType | Enum name when type is enum |
defaultValue | Default value for new records, stored as a string and converted at runtime |
isRequired | Required/not nullable backend and UI validation |
isUnique | Unique value validation |
serverOnly | Hidden from clients, API responses, and UI metadata |
allowSetByClients | Whether create/update clients may set this value |
isMappedToDbField | Whether the property is stored in the database |
foreignKey | Lookup relation metadata |
validators | Backend/UI validation rules |
| Type | Description |
|---|---|
string | Text |
int, long | Whole numbers |
decimal, money | Decimal numbers and money values |
dateTime, date, time | Date/time values |
boolean | True/false |
guid | GUID value |
enum | Integer-backed enum; requires enumType |
file, image | Upload metadata handled by the low-code file pipeline |
Use file or image properties for first-class upload fields:
{
"name": "CoverImage",
"type": "image",
"fileAllowedContentTypes": ["image/*"],
"fileMaxSizeBytes": 5242880,
"imageMaxWidth": 1600,
"imageMaxHeight": 900,
"imageResizeMode": "fit"
}
Use entity attachments when each record can have multiple arbitrary files:
{
"name": "Acme.Campaigns.Campaign",
"attachments": {
"isEnabled": true,
"maxFileCount": 10,
"maxFileSizeBytes": 5242880,
"allowedContentTypes": ["application/pdf", "image/*"]
}
}
{
"name": "OwnerId",
"type": "guid",
"foreignKey": {
"entityName": "Volo.Abp.Identity.IdentityUser",
"displayPropertyName": "UserName",
"access": "none"
}
}
entityName can point to another dynamic entity or a registered reference entity. access controls Foreign Access behavior for dynamic entity relations.
{
"name": "EmailAddress",
"type": "string",
"validators": [
{ "type": "required" },
{ "type": "email" },
{ "type": "maxLength", "length": 255 }
]
}
Common validators include required, minLength, maxLength, stringLength, email, emailAddress, phone, url, creditCard, regularExpression, range, min, and max. Validators can include a custom message.
Pages create runtime routes and menu entries. They also choose how entity data is rendered in React.
{
"name": "campaigns",
"title": "Campaigns",
"icon": "fa-solid fa-bullhorn",
"type": "dataGrid",
"entityName": "Acme.Campaigns.Campaign",
"group": "marketing",
"defaultFileExportMode": 0,
"allowFileBundleExport": true,
"columns": [
{ "propertyName": "Name", "order": 0, "exportOrder": 0 },
{ "propertyName": "Status", "order": 1, "exportOrder": 1 },
{ "propertyName": "Budget", "order": 2, "exportOrder": 2, "exportable": false }
],
"filters": [
{ "propertyName": "Name", "control": "text", "defaultOperator": "contains" },
{ "propertyName": "Status", "control": "select", "defaultOperator": "equal" }
],
"createFormName": "campaign-form",
"editFormName": "campaign-form"
}
Page columns support two independent flags:
| Field | Default | Purpose |
|---|---|---|
visible | true | Renders the field in the React page view |
exportOrder | order | Optional page-level export order. Lower values are exported first |
exportable | true | Page-level export flag managed by Export Fields. Allows the field to be included in Excel, CSV, download-link columns, and file bundle export |
If columns is present, export uses this list as the page-level export policy. exportable: false prevents the field from being exported even if a caller sends the field name manually. exportOrder controls default export order without changing display order. Server-only entity properties are never exportable.
Page export settings:
| Field | Default | Purpose |
|---|---|---|
defaultFileExportMode | 0 | Default spreadsheet output for file/image fields. 0 = file name, 1 = metadata columns, 2 = temporary download-link columns |
allowFileBundleExport | true | Allows Files (.zip) export for exportable file/image columns on the page |
ZIP file bundle export only includes selected page columns that are file or image fields and are exportable. The ZIP contains manifest.csv plus files under files/{recordId}/{fieldName}/{safeFileName}.
| Page type | Required fields | Purpose |
|---|---|---|
dataGrid | entityName | Searchable, sortable CRUD grid |
kanban | entityName, groupByProperty | Cards grouped by an enum/status-like property |
calendar | entityName, calendarStartProperty | Records shown on a calendar |
gallery | entityName | Visual/card list, optionally using galleryImageProperty |
form | entityName, formName | Standalone form page |
dashboard | dashboard | Dashboard visualizations |
Runtime routes use the page name:
/dynamic/<page-name>
/dynamic/<page-name>/create
/dynamic/<page-name>/edit/<record-id>
/dynamic/<page-name>/<record-id>
Forms are named definitions referenced by pages through formName, createFormName, or editFormName.
{
"name": "campaign-form",
"entityName": "Acme.Campaigns.Campaign",
"enableSaveAndNew": true,
"fields": [
{ "id": "name", "label": "Name", "type": "text", "binding": "Name" },
{ "id": "status", "label": "Status", "type": "select", "binding": "Status", "enumType": "Acme.Campaigns.CampaignStatus" },
{ "id": "ownerId", "label": "Owner", "type": "lookup", "binding": "OwnerId" }
],
"layout": {
"tabs": [
{
"id": "main",
"title": "Main",
"isDefault": true,
"groups": [
{
"id": "details",
"title": "Details",
"isDefault": true,
"fields": [
{ "fieldId": "name", "row": 0, "colSpan": 4 },
{ "fieldId": "status", "row": 1, "colSpan": 2 },
{ "fieldId": "ownerId", "row": 1, "colSpan": 2 }
]
}
]
}
]
}
}
Form fields can be text, textarea, number, checkbox, date, datetime, time, file, image, money, select, lookup, guid, or computed. Form rules can hide, show, disable, enable, or set values for fields/groups.
Filters are page-owned. Use control: "auto" unless you need a specific control.
| Property type | Typical operators |
|---|---|
string | contains, equal, notEqual, startsWith, endsWith, notContains, hasValue |
int, long, decimal, money | between, equal, notEqual, greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, hasValue |
date, dateTime, time | between, equal, greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, hasValue |
boolean | All / Yes / No value selector |
enum, lookup, guid | equal, notEqual, in, notIn, hasValue |
file, image | hasValue with All / Yes / No |
hasValue is a UI alias. At runtime, Yes maps to IsNotNull, No maps to IsNull, and All does not add a filter.
Pages can use generated defaults or explicit permission configuration:
{
"permissionConfig": {
"view": "authenticated",
"create": "Acme.Campaigns.Create",
"update": "Acme.Campaigns.Update",
"delete": "Acme.Campaigns.Delete"
}
}
Custom permission definitions live in the top-level permissions section and can be granted through the normal ABP permission management UI.
{
"interceptors": [
{
"commandName": "Create",
"type": "Pre",
"javascript": "if (!args.getValue('Name')) { globalError = 'Name is required.'; }"
}
]
}
See Interceptors and Scripting API.
{
"endpoints": [
{
"name": "GetCampaignStats",
"route": "/api/custom/campaigns/stats",
"method": "GET",
"requireAuthentication": true,
"requiredPermissions": ["Acme.Campaigns"],
"javascript": "var count = await db.count('Acme.Campaigns.Campaign'); return ok({ total: count });"
}
]
}
See Custom Endpoints.
{
"eventHandlers": [
{
"name": "NotifyCampaignCompleted",
"eventName": "Acme.Campaigns.CampaignCompleted",
"javascript": "log('Campaign completed: ' + eventData.id);"
}
],
"backgroundJobs": [
{
"name": "SendCampaignSummary",
"javascript": "log('Sending summary for ' + jobData.campaignId);"
}
],
"backgroundWorkers": [
{
"name": "CampaignCleanup",
"period": 3600000,
"javascript": "log('Cleaning campaign data.');"
}
]
}
Background workers require either period in milliseconds or cronExpression. See Script Actions for event handler, background job, background worker, code editor, and dry-run testing details.
The complete example below shows the logical aggregate shape. Split projects store each descriptor as its own file, but field shapes are the same.
{
"enums": [
{
"name": "Acme.Campaigns.CampaignStatus",
"values": [
{ "name": "Draft", "value": 0 },
{ "name": "Active", "value": 1 },
{ "name": "Completed", "value": 2 }
]
}
],
"entities": [
{
"name": "Acme.Campaigns.Campaign",
"displayName": "Campaigns",
"displayProperty": "Name",
"properties": [
{ "name": "Name", "type": "string", "isRequired": true, "validators": [{ "type": "maxLength", "length": 128 }] },
{ "name": "Status", "type": "enum", "enumType": "Acme.Campaigns.CampaignStatus", "defaultValue": "0" },
{ "name": "Budget", "type": "money" },
{ "name": "StartDate", "type": "date" },
{ "name": "CoverImage", "type": "image", "fileAllowedContentTypes": ["image/*"] }
]
}
],
"forms": [
{
"name": "campaign-form",
"entityName": "Acme.Campaigns.Campaign",
"fields": [
{ "id": "name", "label": "Name", "type": "text", "binding": "Name" },
{ "id": "status", "label": "Status", "type": "select", "binding": "Status", "enumType": "Acme.Campaigns.CampaignStatus" },
{ "id": "budget", "label": "Budget", "type": "money", "binding": "Budget" },
{ "id": "startDate", "label": "Start Date", "type": "date", "binding": "StartDate" },
{ "id": "coverImage", "label": "Cover Image", "type": "image", "binding": "CoverImage" }
],
"layout": {
"tabs": [
{
"id": "main",
"title": "Main",
"isDefault": true,
"groups": [
{
"id": "details",
"title": "Details",
"isDefault": true,
"fields": [
{ "fieldId": "name", "row": 0, "colSpan": 4 },
{ "fieldId": "status", "row": 1, "colSpan": 2 },
{ "fieldId": "budget", "row": 1, "colSpan": 2 },
{ "fieldId": "startDate", "row": 2, "colSpan": 2 },
{ "fieldId": "coverImage", "row": 2, "colSpan": 2 }
]
}
]
}
]
}
}
],
"pageGroups": [
{ "name": "marketing", "title": "Marketing", "icon": "fa-solid fa-bullhorn", "order": 10 }
],
"pages": [
{
"name": "campaigns",
"title": "Campaigns",
"type": "dataGrid",
"entityName": "Acme.Campaigns.Campaign",
"group": "marketing",
"columns": [
{ "propertyName": "Name", "order": 0, "exportOrder": 0 },
{ "propertyName": "Status", "order": 1, "exportOrder": 1 },
{ "propertyName": "Budget", "order": 2, "exportOrder": 2, "exportable": false }
],
"filters": [
{ "propertyName": "Name", "control": "text", "defaultOperator": "contains" },
{ "propertyName": "Status", "control": "select", "defaultOperator": "equal" },
{ "propertyName": "CoverImage", "control": "exists", "defaultOperator": "hasValue" }
],
"createFormName": "campaign-form",
"editFormName": "campaign-form"
}
]
}
Entity shape changes require database migrations before they can be used safely:
In ABP Studio, run the generated migration task for the solution. If you run the application from the command line, use the migration workflow generated by the startup template.