From a93b527228d26561ce7f9f72c28bb78c04077673 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?SAL=C4=B0H=20=C3=96ZKARA?= Date: Wed, 16 Sep 2026 10:31:43 +0300 Subject: [PATCH 1/2] Update low-code JSON schemas for the 10.8 descriptor model - Add apps category and app-descriptor schema; add app, metadata, and extendsLowerLayer to all descriptors - Entity: description/order; property decimalPlaces, currencySymbol, collection, formula, and rollup with mutual-exclusion rules - Foreign key: drop access (reverse access now lives on page relationships) - Enum: displayName/order and per-value displayName/presentation/color/icon - Endpoint: routeScope and useResourceAuthorization - Page: showInMenu, galleryImagePresentation, importEnabled, enumPresentations, relationships, backendFilter expression, page interceptors, export mode 3, boolean column presentation, relative-date filter operators - Dashboard/form: stableId on chart series, filter conditions, and rule actions; full DynamicEntityFilterType list for dashboard filters - Bump manifest to 10.8 and update model-json, foreign-access, data-modeling, and fluent-api docs accordingly --- docs/en/low-code/data-modeling.md | 2 +- docs/en/low-code/fluent-api.md | 13 +- docs/en/low-code/foreign-access.md | 117 ++++++----- docs/en/low-code/model-json.md | 99 ++++++++-- .../definitions/app-descriptor.schema.json | 48 +++++ ...olean-value-display-descriptor.schema.json | 29 +++ .../boolean-value-presentation.schema.json | 19 ++ ...command-interceptor-descriptor.schema.json | 5 +- .../dashboard-chart-descriptor.schema.json | 9 +- .../dashboard-filter-descriptor.schema.json | 63 +++++- ...shboard-number-item-descriptor.schema.json | 8 +- ...board-visualization-descriptor.schema.json | 4 +- .../descriptor-metadata.schema.json | 17 ++ .../endpoint-descriptor.schema.json | 52 ++++- ...ss-field-validation-descriptor.schema.json | 4 +- .../definitions/entity-descriptor.schema.json | 44 ++++- .../entity-formula-descriptor.schema.json | 25 +++ ...property-collection-descriptor.schema.json | 25 +++ .../entity-property-descriptor.schema.json | 52 ++++- .../entity-rollup-descriptor.schema.json | 43 ++++ .../definitions/enum-descriptor.schema.json | 149 +++++++++----- .../enum-value-presentation.schema.json | 17 ++ .../foreign-key-descriptor.schema.json | 13 +- .../definitions/form-descriptor.schema.json | 24 ++- .../form-rule-descriptor.schema.json | 5 + ...page-backend-filter-expression.schema.json | 135 +++++++++++++ .../page-column-descriptor.schema.json | 48 ++++- ...command-interceptor-descriptor.schema.json | 38 ++++ .../definitions/page-descriptor.schema.json | 183 ++++++++++++------ ...e-enum-presentation-descriptor.schema.json | 62 ++++++ .../page-filter-descriptor.schema.json | 24 ++- .../page-group-descriptor.schema.json | 31 ++- .../page-relationship-descriptor.schema.json | 107 ++++++++++ .../permission-descriptor.schema.json | 26 ++- .../presentation-icon-reference.schema.json | 26 +++ ...ript-background-job-descriptor.schema.json | 24 ++- ...t-background-worker-descriptor.schema.json | 71 +++++-- ...cript-event-handler-descriptor.schema.json | 24 ++- schemas/low-code/manifest.json | 5 +- 39 files changed, 1428 insertions(+), 262 deletions(-) create mode 100644 schemas/low-code/definitions/app-descriptor.schema.json create mode 100644 schemas/low-code/definitions/boolean-value-display-descriptor.schema.json create mode 100644 schemas/low-code/definitions/boolean-value-presentation.schema.json create mode 100644 schemas/low-code/definitions/descriptor-metadata.schema.json create mode 100644 schemas/low-code/definitions/entity-formula-descriptor.schema.json create mode 100644 schemas/low-code/definitions/entity-property-collection-descriptor.schema.json create mode 100644 schemas/low-code/definitions/entity-rollup-descriptor.schema.json create mode 100644 schemas/low-code/definitions/enum-value-presentation.schema.json create mode 100644 schemas/low-code/definitions/page-backend-filter-expression.schema.json create mode 100644 schemas/low-code/definitions/page-command-interceptor-descriptor.schema.json create mode 100644 schemas/low-code/definitions/page-enum-presentation-descriptor.schema.json create mode 100644 schemas/low-code/definitions/page-relationship-descriptor.schema.json create mode 100644 schemas/low-code/definitions/presentation-icon-reference.schema.json diff --git a/docs/en/low-code/data-modeling.md b/docs/en/low-code/data-modeling.md index 8c3de52d6e..2da112a27a 100644 --- a/docs/en/low-code/data-modeling.md +++ b/docs/en/low-code/data-modeling.md @@ -104,7 +104,7 @@ A foreign key defines the schema direction. A page relationship defines how reco } ``` -`access` can be `none`, `view`, or `edit`. The generated modes build the related page or form from the source entity; the explicit modes reuse named page and form descriptors. +`access` can be `view` or `edit`; omit the relationship entirely when the foreign key should stay lookup-only. `relatedPageMode`, `createFormMode`, and `editFormMode` are required. The generated modes build the related page or form from the source entity; the explicit modes reuse named page and form descriptors, and `inherit` reuses the related page's own forms. See [Foreign Access](foreign-access.md) for the runtime APIs and UI behavior used by these relationships. diff --git a/docs/en/low-code/fluent-api.md b/docs/en/low-code/fluent-api.md index 73aa64a534..e28b12e5db 100644 --- a/docs/en/low-code/fluent-api.md +++ b/docs/en/low-code/fluent-api.md @@ -64,7 +64,7 @@ public class Product : DynamicEntityBase public ProductStatus Status { get; set; } - [DynamicForeignKey("Catalog.Categories.Category", "Name", ForeignAccess.View)] + [DynamicForeignKey("Catalog.Categories.Category", "Name")] public Guid? CategoryId { get; set; } [DynamicPropertyFileOptions( @@ -322,17 +322,12 @@ public class Product : DynamicEntityBase [DynamicPropertyDefaultValue("0")] public decimal Price { get; set; } - [DynamicForeignKey( - "Catalog.Categories.Category", - "Name", - ForeignAccess.View - )] + [DynamicForeignKey("Catalog.Categories.Category", "Name")] public Guid? CategoryId { get; set; } [DynamicForeignKey( "Catalog.Products.Product", "Name", - ForeignAccess.View, DependsOnPropertyName = nameof(CategoryId), DependsOnFilterPropertyName = "CategoryId" )] @@ -528,7 +523,7 @@ The `Configure(...)` callback gives you an `EntityDescriptor`. | `AsImage(long? maxSizeBytes = null, int? maxWidth = null, int? maxHeight = null, string? resizeMode = null, params string[] allowedContentTypes)` | Sets `Type = Image` and image constraints | | `WithDefaultValue(string? defaultValue)` | Sets `DefaultValue` | | `WithEnumType(string enumType)` | Sets `Type = Enum` and `EnumType` | -| `WithForeignKey(string entityName, string? displayPropertyName = null, ForeignAccess access = ForeignAccess.None, string? dependsOnPropertyName = null, string? dependsOnFilterPropertyName = null)` | Configures the relation in one call | +| `WithForeignKey(string entityName, string? displayPropertyName = null, string? dependsOnPropertyName = null, string? dependsOnFilterPropertyName = null)` | Configures the relation in one call. Reverse access is configured on page `relationships`, see [Foreign Access](foreign-access.md) | | `AsServerOnly(bool serverOnly = true)` | Sets `ServerOnly` | | `AsRequired(bool isRequired = true)` | Sets `IsRequired` | @@ -565,7 +560,7 @@ AbpDynamicEntityConfig.EntityConfigurations.Configure( .WithEnumType("Catalog.Products.ProductStatus"); entity.AddOrGetProperty("CategoryId") - .WithForeignKey("Catalog.Categories.Category", "Name", ForeignAccess.View); + .WithForeignKey("Catalog.Categories.Category", "Name"); entity.AddOrGetProperty("HeroImage") .AsImage( diff --git a/docs/en/low-code/foreign-access.md b/docs/en/low-code/foreign-access.md index 44b04e9584..08af10ea7e 100644 --- a/docs/en/low-code/foreign-access.md +++ b/docs/en/low-code/foreign-access.md @@ -13,100 +13,121 @@ Use the [Low-Code Designer](designer.md) to review relation metadata visually. T Foreign Access controls how related **dynamic entities** can be accessed through foreign key relationships. It determines whether users can view or manage related data directly from the **target entity's** UI. -The foreign key defines the schema relation and default reverse-access level. A page can additionally define a page-specific relationship that selects generated or named related pages/forms and separate authorization. See [Data Modeling and Page Behavior](data-modeling.md#reverse-relationships). +The foreign key defines only the schema relation. Reverse access is configured per page: the target entity's page defines a `relationships[]` entry that selects the access level, generated or named related pages/forms, and optional separate authorization. See [Data Modeling and Page Behavior](data-modeling.md#reverse-relationships). > **Important:** Foreign Access only works between **dynamic entities**. It does not apply to [reference entities](reference-entities.md) because they are read-only and don't have UI pages. ## Access Levels -The `ForeignAccess` enum defines three levels: +The `ForeignAccess` enum defines three levels. A page relationship uses `View` or `Edit`; a foreign key without a page relationship behaves like `None`. | Level | Value | Description | |-------|-------|-------------| -| `None` | 0 | No access from the target entity side. The relationship exists only for lookups. | -| `View` | 1 | Read-only access. Users can view related records from the target entity's action menu. | -| `Edit` | 2 | Full CRUD access. Users can create, update, and delete related records from the target entity's action menu. | +| `None` | 0 | No access from the target entity side. The relationship exists only for lookups. This is the behavior of a foreign key that no page relationship references. | +| `View` | 1 | Read-only access. Users can view related records from the target entity's page. | +| `Edit` | 2 | Full CRUD access. Users can create, update, and delete related records from the target entity's page. | -## Configuring with Attributes +## Defining the Foreign Key -Use the third parameter of `[DynamicForeignKey]`: +The foreign key only declares the schema direction. With attributes: ````csharp [DynamicEntity] public class Order { - [DynamicForeignKey("MyApp.Customers.Customer", "Name", ForeignAccess.Edit)] + [DynamicForeignKey("MyApp.Customers.Customer", "Name")] public Guid CustomerId { get; set; } } ```` -## Configuring with Fluent API +With the Fluent API: ````csharp AbpDynamicEntityConfig.EntityConfigurations.Configure( "MyApp.Orders.Order", entity => { - var customerIdProperty = entity.AddOrGetProperty("CustomerId"); - customerIdProperty.ForeignKey = new ForeignKeyDescriptor - { - EntityName = "MyApp.Customers.Customer", - DisplayPropertyName = "Name", - Access = ForeignAccess.Edit - }; + entity.AddOrGetProperty("CustomerId") + .WithForeignKey("MyApp.Customers.Customer", "Name"); } ); ```` -## Configuring in JSON Descriptors - -Set the `access` field on a foreign key property: +In JSON descriptors: ```json { "name": "CustomerId", "foreignKey": { "entityName": "LowCodeDemo.Customers.Customer", - "displayPropertyName": "Name", - "access": "edit" + "displayPropertyName": "Name" } } ``` -### Examples from the Demo Application +## Configuring Access in Page Descriptors -**Edit access** — Orders can be managed from the Customer page: +Reverse access is defined on the **target entity's page** with a `relationships[]` entry. `sourceEntityName` and `sourcePropertyName` identify the foreign key that points back to the page entity: ```json { - "name": "LowCodeDemo.Orders.Order", - "properties": [ + "name": "customers", + "title": "Customers", + "type": "dataGrid", + "entityName": "LowCodeDemo.Customers.Customer", + "relationships": [ { - "name": "CustomerId", - "foreignKey": { - "entityName": "LowCodeDemo.Customers.Customer", - "access": "edit" - } + "id": "orders-customer", + "sourceEntityName": "LowCodeDemo.Orders.Order", + "sourcePropertyName": "CustomerId", + "access": "edit", + "relatedPageMode": "page", + "relatedPageName": "orders", + "createFormMode": "generated", + "editFormMode": "generated" } ] } ``` -**View access** — Visited countries are viewable from the Country page: +| Field | Description | +|-------|-------------| +| `id` | Stable identifier unique within the page; used by relationship permissions and routes | +| `access` | `view` or `edit` | +| `relatedPageMode` | `generated` builds the related list from the source entity; `page` reuses `relatedPageName` | +| `createFormMode` / `editFormMode` | `generated`, `inherit` (reuse the related page's forms), or `form` with `createFormName` / `editFormName` | +| `useSeparatePermission` | Resolve view/create/update/delete for this relationship separately from the host page | +| `permissionConfig` | Optional permission overrides used with `useSeparatePermission` | + +### Examples from the Demo Application + +**Edit access** — Orders can be managed from the Customer page (`pages/customers.json`): ```json { - "name": "LowCodeDemo.Customers.VisitedCountry", - "parent": "LowCodeDemo.Customers.Customer", - "properties": [ - { - "name": "CountryId", - "foreignKey": { - "entityName": "LowCodeDemo.Countries.Country", - "access": "view" - } - } - ] + "id": "orders-customer", + "sourceEntityName": "LowCodeDemo.Orders.Order", + "sourcePropertyName": "CustomerId", + "access": "edit", + "relatedPageMode": "page", + "relatedPageName": "orders", + "createFormMode": "generated", + "editFormMode": "generated" +} +``` + +**View access** — Warehouses managed by a customer are viewable from the Customer page: + +```json +{ + "id": "warehouses-manager-customer", + "sourceEntityName": "LowCodeDemo.Inventory.Warehouse", + "sourcePropertyName": "ManagerCustomerId", + "access": "view", + "relatedPageMode": "page", + "relatedPageName": "warehouses", + "createFormMode": "generated", + "editFormMode": "generated" } ``` @@ -138,14 +159,14 @@ A generated page relationship can set `useSeparatePermission: true`. In that mod ## How It Works -The `ForeignAccessRelation` class stores the relationship metadata: +The `PageRelationshipDescriptor` on the target entity's page stores the relationship metadata: -* **Source entity** — the dynamic entity with the foreign key (e.g., `Order`) -* **Target entity** — the dynamic entity being referenced (e.g., `Customer`) -* **Foreign key property** — the property name (e.g., `CustomerId`) -* **Access level** — `None`, `View`, or `Edit` +* **Source entity** — the dynamic entity with the foreign key (e.g., `Order`), from `sourceEntityName` +* **Target entity** — the dynamic entity being referenced (e.g., `Customer`), the page `entityName` +* **Foreign key property** — the property name (e.g., `CustomerId`), from `sourcePropertyName` +* **Access level** — `View` or `Edit` -The `DynamicEntityAppService` checks these relations when building entity actions and filtering data. +`DynamicForeignAccessService` resolves these relationships when building entity actions and filtering related data. > **Terminology:** In foreign access context, "target entity" refers to the entity whose UI shows the action menu (the entity being pointed to by the foreign key). This is different from "reference entity" which specifically means an existing C# entity registered for read-only access. diff --git a/docs/en/low-code/model-json.md b/docs/en/low-code/model-json.md index 5773c905c1..46132e655a 100644 --- a/docs/en/low-code/model-json.md +++ b/docs/en/low-code/model-json.md @@ -1,7 +1,7 @@ ```json //[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." + "Description": "Define ABP Low-Code descriptor metadata and descriptor schemas for apps, dynamic entities, pages, forms, filters, permissions, script endpoints, event handlers, background jobs, and workers." } ``` @@ -40,10 +40,11 @@ Keep the whole `_Dynamic` folder and the generated initializer in source control Layout conventions: -* `entities/` and `enums/` usually follow namespace-like folders such as `entities/Acme/Catalog/Product.json`. +* `entities/`, `enums/`, and `permissions/` usually follow namespace-like folders such as `entities/Acme/Catalog/Product.json`. * `pageGroups/` usually stays flat as `pageGroups/{groupName}.json`. * `pages/` stays flat as `pages/{pageName}.json`, even when the page belongs to a page group or is a dashboard. * Dashboard pages live in `pages/`; there is no separate dashboard descriptor folder. +* `apps/` holds one file per non-default [app](#apps), for example `apps/crm.json`. Descriptors that belong to an app are written under an app subfolder of their category, for example `entities/crm/Acme/Crm/Contact.json` or `pages/crm/contacts.json`. * The runtime scans the directory tree directly. Do not add a combined index file next to `model/`. ## Example Files and Validation @@ -83,15 +84,16 @@ The schema files live in the ABP repository under `schemas/low-code`. Use the br The schema manifest is published at: ```text -https://raw.githubusercontent.com/abpframework/abp/rel-10.5/schemas/low-code/manifest.json +https://raw.githubusercontent.com/abpframework/abp/rel-10.8/schemas/low-code/manifest.json ``` -For another version, replace `rel-10.5` with the matching ABP branch or tag. +For another version, replace `rel-10.8` with the matching ABP branch or tag. The runtime writes the same `rel-{major}.{minor}` branch into the `$schema` reference of generated descriptor files. The manifest maps each descriptor collection to its descriptor schema: | Descriptor collection | Descriptor schema | |-----------------------|-------------------| +| `apps` | `definitions/app-descriptor.schema.json` | | `enums` | `definitions/enum-descriptor.schema.json` | | `entities` | `definitions/entity-descriptor.schema.json` | | `endpoints` | `definitions/endpoint-descriptor.schema.json` | @@ -109,7 +111,7 @@ Use the descriptor schema directly when a descriptor is stored as its own JSON f ```json { - "$schema": "https://raw.githubusercontent.com/abpframework/abp/rel-10.5/schemas/low-code/definitions/entity-descriptor.schema.json", + "$schema": "https://raw.githubusercontent.com/abpframework/abp/rel-10.8/schemas/low-code/definitions/entity-descriptor.schema.json", "name": "Acme.Catalog.Product", "displayName": "Products", "properties": [] @@ -126,6 +128,7 @@ When descriptor metadata is viewed as an aggregate document, the logical section ```json { + "apps": [], "enums": [], "entities": [], "endpoints": [], @@ -141,6 +144,7 @@ When descriptor metadata is viewed as an aggregate document, the logical section | Section | Description | |---------|-------------| +| `apps` | Named app scopes that partition the model; descriptors reference them through `app` | | `enums` | Reusable enum definitions | | `entities` | Dynamic entities, properties, relations, attachments, validations, and interceptors | | `endpoints` | JavaScript-backed custom HTTP endpoints | @@ -152,6 +156,47 @@ When descriptor metadata is viewed as an aggregate document, the logical section | `forms` | Named form definitions referenced by pages | | `permissions` | Custom permission definitions referenced by pages and endpoints | +Every descriptor also accepts these common fields: + +| Field | Description | +|-------|-------------| +| `app` | Name of the owning [app](#apps). Omit for the default app | +| `metadata` | Free-form string key/value annotations for tooling and documentation. Values must be strings or `null` | +| `extendsLowerLayer` | When `true`, the descriptor extends a descriptor with the same name from a lower model layer (for example code-first attributes) instead of defining a new one; only the overridden fields are required | + +## Apps + +Apps split one low-code model into independently named scopes. The default app is implicit: descriptors without an `app` field belong to it. Create an app descriptor only when a group of entities, pages, forms, and scripts should be isolated under its own name. + +```json +{ + "name": "crm", + "displayName": "CRM", + "description": "Customer relationship management app.", + "isArchived": false +} +``` + +| Field | Description | +|-------|-------------| +| `name` | Required lowercase kebab-case identifier (maximum 64 characters), for example `crm` or `field-service`. `default` is reserved for the implicit default app | +| `displayName` | Required user-facing title (maximum 128 characters) | +| `description` | Optional description | +| `isArchived` | Hides the app from active app lists without deleting its descriptors | + +Descriptors reference the app by name: + +```json +{ + "name": "Acme.Crm.Contact", + "app": "crm", + "displayName": "Contacts", + "properties": [] +} +``` + +App-scoped entities are addressed at runtime as `:`, app-scoped endpoints can publish beneath `/api/low-code/apps//endpoints` with `routeScope: "app"`, and permission children inherit the parent `app` when they do not set their own. + ## Enums Define enums before properties that reference them: @@ -161,17 +206,20 @@ Define enums before properties that reference them: "enums": [ { "name": "Acme.Catalog.ProductStatus", + "displayName": "Product Status", "values": [ { "name": "Draft", "value": 0 }, - { "name": "Active", "value": 1 }, + { "name": "Active", "value": 1, "presentation": "badge", "color": "#16A34A" }, { "name": "Paused", "value": 2 }, - { "name": "Completed", "value": 3 } + { "name": "Completed", "value": 3, "presentation": "iconOnly", "icon": { "kind": "class", "value": "fa-solid fa-check" } } ] } ] } ``` +Enum values accept optional `displayName`, `presentation` (`text`, `badge`, or `iconOnly`), `color`, and `icon` display metadata. See [Data Modeling and Page Behavior](data-modeling.md#enum-and-boolean-presentation) for page-level overrides. + Use the enum from a property with `type: "enum"` and `enumType`: ```json @@ -202,6 +250,8 @@ Entities describe the persisted data model. UI is not configured with legacy pro |-------|-------------| | `name` | Required stable full entity name, for example `Acme.Catalog.Product` | | `displayName` | Default plural/screen label | +| `description` | Optional designer documentation text | +| `order` | Optional designer/list sort order | | `displayProperty` | Property shown in lookups and foreign key display values | | `parent` | Parent entity name for child/detail entities | | `attachments` | Record-level attachment settings | @@ -240,10 +290,14 @@ Entities describe the persisted data model. UI is not configured with legacy pro | `isMappedToDbField` | Whether a dynamic scalar property uses a dedicated physical column instead of dynamic data storage | | `decimalPlaces` | Decimal scale for `decimal` and `money` properties | | `currencySymbol` | Optional UI currency symbol for `money` properties | -| `collection` | Primitive collection settings: optional `maxCount` and `uniqueItems` | +| `collection` | Primitive collection settings: optional `maxCount` and required `uniqueItems` | +| `formula` | Virtual calculated value: `expression` and `resultType` | +| `rollup` | Virtual aggregate over related records: `sourceEntityName`, `foreignKeyPropertyName`, `operation`, and optional `valuePropertyName` | | `foreignKey` | Lookup relation metadata | | `validators` | Backend/UI validation rules | +`collection`, `formula`, `rollup`, and `foreignKey` are mutually exclusive on one property. Formula and rollup properties are read-only and never persisted; the runtime forces `isMappedToDbField`, `allowSetByClients`, `isRequired`, and `isUnique` to `false` for them. + `isMappedToDbField: true` creates a dedicated scalar column. Other dynamic scalar properties use the configured dynamic data mapping, which is JSON storage by default and can be configured as individual columns. Primitive collections use normalized collection tables. See [Data Modeling and Page Behavior](data-modeling.md) for storage, collections, related fields, presentations, and backend filters. For virtual calculated fields and related-record aggregates, see [Calculated and Rollup Properties](formula-properties.md). The [Low-Code Expression Language](expression-language.md) reference documents the scalar syntax used by calculated properties and formula backfills. @@ -310,13 +364,12 @@ Use entity `attachments` when each record can have multiple arbitrary files: "type": "guid", "foreignKey": { "entityName": "Volo.Abp.Identity.IdentityUser", - "displayPropertyName": "UserName", - "access": "none" + "displayPropertyName": "UserName" } } ``` -`entityName` can point to another dynamic entity or a registered [reference entity](reference-entities.md). `access` controls [Foreign Access](foreign-access.md) behavior for dynamic entity relations. +`entityName` can point to another dynamic entity or a registered [reference entity](reference-entities.md). Use `dependsOn` (`propertyName` and `filterPropertyName`) for cascading lookups. Reverse access from the referenced entity side is not configured on the foreign key; define a page `relationships[]` entry on the target entity's page instead. See [Foreign Access](foreign-access.md). ### Validators @@ -377,12 +430,23 @@ 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 | +| `defaultFileExportMode` | `0` | Default spreadsheet output for file/image fields. `0` = file name, `1` = metadata columns, `2` = temporary download-link columns, `3` = file name with download link | | `allowFileBundleExport` | `true` | Allows **Files (.zip)** export for exportable file/image columns on the page | `importEnabled` controls whether the React runtime exposes guided Excel/CSV import for the page. See [Data Import](data-import.md) for mapping and merge behavior. -Page column and filter `propertyName` values may follow foreign keys, for example `CustomerId.CountryId.Name`. Related paths are limited by the configured query depth and return only the requested projection. Page columns can also define enum and boolean presentation metadata. See [Data Modeling and Page Behavior](data-modeling.md). +Other page-level fields: + +| Field | Purpose | +|-------|---------| +| `showInMenu` | Set `false` for pages reached only through relationships, `saveSuccessPageName`, or direct links | +| `galleryImagePresentation` | `coverLightbox` or `inlineSlider` for gallery pages; `inlineSlider` suits image collection properties | +| `enumPresentations` | Page-level overrides of enum value label, presentation, color, and icon | +| `relationships` | Reverse relationships (related records that point back to the page record). See [Data Modeling and Page Behavior](data-modeling.md#reverse-relationships) | +| `backendFilter` | Server-enforced filter expression. See [Filters](#filters) | +| `interceptors` | Page-scoped Create/Update/Delete interceptors with an `entityExecutionOrder` of `entityFirst`, `pageFirst`, or `skipEntity`. See [Interceptors](interceptors.md) | + +Page column and filter `propertyName` values may follow foreign keys, for example `CustomerId.CountryId.Name`. Related paths are limited by the configured query depth and return only the requested projection. Page columns can also define boolean presentation metadata with `booleanPresentation` and `booleanValues`. See [Data Modeling and Page Behavior](data-modeling.md). 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}`. @@ -456,14 +520,14 @@ Filters are page-owned. Use `control: "auto"` unless you need a specific control |---------------|-------------------| | `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` | +| `date`, `dateTime`, `time` | `between`, `equal`, `greaterThan`, `greaterThanOrEqual`, `lessThan`, `lessThanOrEqual`, `hasValue`, and the relative-date operators `today`, `beforeToday`, `thisWeek`, `lastWeek`, `thisMonth`, `lastMonth`, `thisYear`, `lastYear` | | `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. +`hasValue` is a UI alias. At runtime, `Yes` maps to `IsNotNull`, `No` maps to `IsNull`, and `All` does not add a filter. Relative-date operators need no value; the server resolves the range at query time. -Use a page `backendFilter` when a condition must always be applied by the server. The recursive expression supports `and`/`or` groups and static, JavaScript, or registered-provider values. Backend filters are combined with the filters above and are not removable client state. See [Data Modeling and Page Behavior](data-modeling.md#backend-filters). +Use a page `backendFilter` when a condition must always be applied by the server. The root is a single condition or a group with `items`; inside a group the first item has no `logic` and every following item sets `logic` to `and` or `or`. Each condition names a `propertyName`, an explicit `operator`, and exactly one value source: a static `value`, a registered `valueProvider`, or a `javaScript` expression. Backend filters are combined with the filters above and are not removable client state. See [Data Modeling and Page Behavior](data-modeling.md#backend-filters). ## Permissions @@ -510,6 +574,7 @@ See [Interceptors](interceptors.md) and [Scripting API](scripting-api.md). { "name": "GetProductStats", "route": "/api/custom/products/stats", + "routeScope": "global", "method": "GET", "requireAuthentication": true, "useResourceAuthorization": false, @@ -520,7 +585,7 @@ See [Interceptors](interceptors.md) and [Scripting API](scripting-api.md). } ``` -See [Custom Endpoints](custom-endpoints.md). +`routeScope` defaults to `global`, which publishes `route` unchanged. Endpoints that belong to an [app](#apps) can set `routeScope: "app"` to publish beneath `/api/low-code/apps//endpoints`. See [Custom Endpoints](custom-endpoints.md). ### Event Handlers, Jobs, and Workers diff --git a/schemas/low-code/definitions/app-descriptor.schema.json b/schemas/low-code/definitions/app-descriptor.schema.json new file mode 100644 index 0000000000..0a17f739a9 --- /dev/null +++ b/schemas/low-code/definitions/app-descriptor.schema.json @@ -0,0 +1,48 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "app-descriptor.schema.json", + "title": "AppDescriptor", + "description": "Describes a low-code app. Apps partition the model into independently named scopes: other descriptors reference their owning app through the `app` field, and the default app is implicit.", + "markdownDescription": "AI guidance: create an app only when a group of entities, pages, forms, and scripts should be isolated under its own name. `name` is a lowercase kebab-case identifier such as `crm` or `field-service` and becomes part of runtime entity names (`:`), app-scoped endpoint routes, and split descriptor file paths (`entities//...`). The reserved name `default` is the implicit app; descriptors without an `app` field belong to it. Set `isArchived` to hide an app without deleting its descriptors.", + "type": "object", + "properties": { + "$schema": { + "type": "string", + "description": "Optional schema reference used when this descriptor is stored as a model descriptor file." + }, + "name": { + "type": "string", + "description": "Stable lowercase kebab-case app name, for example 'crm' or 'field-service'. Maximum 64 characters. 'default' is the implicit default app.", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" + }, + "displayName": { + "type": "string", + "description": "User-facing app title shown by the designer and admin console. Maximum 128 characters.", + "minLength": 1, + "maxLength": 128 + }, + "description": { + "type": ["string", "null"], + "description": "Optional description for designer documentation." + }, + "isArchived": { + "type": "boolean", + "description": "When true, the app is archived and hidden from active app lists. Descriptors that belong to the app are kept.", + "default": false + }, + "metadata": { + "$ref": "descriptor-metadata.schema.json" + } + }, + "required": ["name", "displayName"], + "additionalProperties": false, + "examples": [ + { + "name": "crm", + "displayName": "CRM", + "description": "Customer relationship management app." + } + ] +} diff --git a/schemas/low-code/definitions/boolean-value-display-descriptor.schema.json b/schemas/low-code/definitions/boolean-value-display-descriptor.schema.json new file mode 100644 index 0000000000..23140df946 --- /dev/null +++ b/schemas/low-code/definitions/boolean-value-display-descriptor.schema.json @@ -0,0 +1,29 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "boolean-value-display-descriptor.schema.json", + "title": "BooleanValueDisplayDescriptor", + "description": "Display metadata for one boolean state (true, false, or null) of a page column.", + "markdownDescription": "AI guidance: set only the fields you want to override. `displayName` replaces the default Yes/No/empty label, `color` is used by badge presentation (hex or CSS color), and `icon` is used by badge/iconOnly presentation. A `null` value for a field explicitly clears an inherited value when the page extends a lower model layer.", + "type": "object", + "properties": { + "displayName": { + "type": ["string", "null"], + "description": "Label for this boolean state, for example 'Active' or 'Inactive'." + }, + "color": { + "type": ["string", "null"], + "description": "Badge color for this state, for example '#16A34A'." + }, + "icon": { + "oneOf": [ + { "$ref": "presentation-icon-reference.schema.json" }, + { "type": "null" } + ], + "description": "Icon for this state used by badge and iconOnly presentations." + } + }, + "additionalProperties": false, + "examples": [ + { "displayName": "Active", "color": "#16A34A", "icon": { "kind": "class", "value": "fa-solid fa-check" } } + ] +} diff --git a/schemas/low-code/definitions/boolean-value-presentation.schema.json b/schemas/low-code/definitions/boolean-value-presentation.schema.json new file mode 100644 index 0000000000..947a14058f --- /dev/null +++ b/schemas/low-code/definitions/boolean-value-presentation.schema.json @@ -0,0 +1,19 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "boolean-value-presentation.schema.json", + "title": "BooleanValuePresentation", + "description": "How a boolean page column is rendered. Prefer lower-case values in descriptor JSON; PascalCase aliases are accepted for compatibility.", + "markdownDescription": "`text` renders the configured display names (or Yes/No). `checkbox` renders a read-only check mark. `badge` renders a colored badge. `iconOnly` renders only the configured icon. Per-value labels, colors, and icons come from the column `booleanValues` object.", + "type": "string", + "enum": ["text", "Text", "checkbox", "Checkbox", "badge", "Badge", "iconOnly", "IconOnly"], + "enumDescriptions": [ + "Plain text display name.", + "Plain text display name.", + "Read-only checkbox.", + "Read-only checkbox.", + "Colored badge.", + "Colored badge.", + "Icon only, display name as tooltip.", + "Icon only, display name as tooltip." + ] +} diff --git a/schemas/low-code/definitions/command-interceptor-descriptor.schema.json b/schemas/low-code/definitions/command-interceptor-descriptor.schema.json index ee1fc6d49a..0cacbb1337 100644 --- a/schemas/low-code/definitions/command-interceptor-descriptor.schema.json +++ b/schemas/low-code/definitions/command-interceptor-descriptor.schema.json @@ -8,8 +8,9 @@ "properties": { "commandName": { "type": "string", - "description": "Entity command to intercept: Create, Update, or Delete.", - "enum": ["Create", "Update", "Delete"] + "description": "Entity command to intercept: Create, Update, Delete, or the name of a custom command registered for this entity with [CustomCommand].", + "minLength": 1, + "examples": ["Create", "Update", "Delete"] }, "type": { "$ref": "interceptor-type.schema.json", diff --git a/schemas/low-code/definitions/dashboard-chart-descriptor.schema.json b/schemas/low-code/definitions/dashboard-chart-descriptor.schema.json index ade648db0f..9178db24ce 100644 --- a/schemas/low-code/definitions/dashboard-chart-descriptor.schema.json +++ b/schemas/low-code/definitions/dashboard-chart-descriptor.schema.json @@ -36,16 +36,21 @@ "items": { "type": "object", "properties": { + "stableId": { + "type": "string", + "description": "Optional stable identifier assigned by the designer so model history and mutations can address this series. Omit in hand-written descriptors; the runtime generates one when missing.", + "minLength": 1 + }, "aggregation": { "$ref": "dashboard-aggregation-type.schema.json" }, "property": { "type": ["string", "null"], - "description": "Property name for sum/average/min/max/percent aggregations. Omit for count." + "description": "Property name for sum/average/min/max/percent aggregations. Omit for count." }, "label": { "type": ["string", "null"], - "description": "Display label for this series. Omit to derive from aggregation/property." + "description": "Display label for this series. Omit to derive from aggregation/property." }, "color": { "type": ["string", "null"] diff --git a/schemas/low-code/definitions/dashboard-filter-descriptor.schema.json b/schemas/low-code/definitions/dashboard-filter-descriptor.schema.json index 93cb76e821..a8bfab04ff 100644 --- a/schemas/low-code/definitions/dashboard-filter-descriptor.schema.json +++ b/schemas/low-code/definitions/dashboard-filter-descriptor.schema.json @@ -3,7 +3,7 @@ "$id": "dashboard-filter-descriptor.schema.json", "title": "DashboardFilterDescriptor", "description": "Static filter applied to a dashboard visualization or KPI item.", - "markdownDescription": "AI guidance: use dashboard filters to constrain the data behind a visualization, for example only active records or only records above a threshold. Each condition property must exist on the visualization/item entity. Combine conditions with `operator: \"and\"` or `operator: \"or\"`.", + "markdownDescription": "AI guidance: use dashboard filters to constrain the data behind a visualization, for example only active records or only records above a threshold. Each condition property must exist on the visualization/item entity. Combine conditions with `operator: \"and\"` or `operator: \"or\"`. `isNull`, `isNotNull`, and relative-date filter types such as `thisMonth` do not need a `value`.", "type": "object", "properties": { "operator": { @@ -16,17 +16,71 @@ "items": { "type": "object", "properties": { + "stableId": { + "type": "string", + "description": "Optional stable identifier assigned by the designer so model history and mutations can address this condition. Omit in hand-written descriptors; the runtime generates one when missing.", + "minLength": 1 + }, "property": { "type": "string", "description": "Property name to filter on. Must exist on the visualization/item entityName." }, "filterType": { "type": "string", - "enum": ["equal", "notEqual", "contains", "greaterThan", "lessThan", "isNull", "isNotNull"], + "description": "Comparison applied to the property. Prefer lower-camel-case values; PascalCase aliases are accepted for compatibility.", + "enum": [ + "equal", + "notEqual", + "contains", + "notContains", + "startsWith", + "endsWith", + "greaterThan", + "greaterThanOrEqual", + "lessThan", + "lessThanOrEqual", + "between", + "isNull", + "isNotNull", + "in", + "notIn", + "thisWeek", + "lastWeek", + "thisMonth", + "lastMonth", + "thisYear", + "lastYear", + "today", + "beforeToday", + "Equal", + "NotEqual", + "Contains", + "NotContains", + "StartsWith", + "EndsWith", + "GreaterThan", + "GreaterThanOrEqual", + "LessThan", + "LessThanOrEqual", + "Between", + "IsNull", + "IsNotNull", + "In", + "NotIn", + "ThisWeek", + "LastWeek", + "ThisMonth", + "LastMonth", + "ThisYear", + "LastYear", + "Today", + "BeforeToday" + ], "default": "equal" }, "value": { - "description": "Filter value. Shape depends on filterType and target property type." + "type": ["string", "number", "boolean", "null"], + "description": "Filter value, stored as a string in descriptor JSON. Shape depends on filterType and target property type; omit for isNull/isNotNull and relative-date filter types." } }, "required": ["property", "filterType"], @@ -40,7 +94,8 @@ { "operator": "and", "conditions": [ - { "property": "Status", "filterType": "equal", "value": 1 } + { "property": "Status", "filterType": "equal", "value": "1" }, + { "property": "StartDate", "filterType": "thisMonth" } ] } ] diff --git a/schemas/low-code/definitions/dashboard-number-item-descriptor.schema.json b/schemas/low-code/definitions/dashboard-number-item-descriptor.schema.json index eb98b09ac4..cad3985eaf 100644 --- a/schemas/low-code/definitions/dashboard-number-item-descriptor.schema.json +++ b/schemas/low-code/definitions/dashboard-number-item-descriptor.schema.json @@ -15,6 +15,10 @@ "type": "string", "description": "Display title for this KPI." }, + "order": { + "type": ["integer", "null"], + "description": "Order of this item inside the container. When omitted, array order is used." + }, "entityName": { "type": "string", "description": "Entity this number item sources data from. Must match an entity descriptor or known reference entity.", @@ -38,8 +42,8 @@ "description": "Display color name (blue, green, red, purple, orange, indigo, amber, teal)" }, "globalDateFilterProperty": { - "type": "string", - "description": "Date/DateTime property used to apply dashboard global date filters. Defaults to CreationTime when omitted." + "type": ["string", "null"], + "description": "Date/DateTime property used to apply dashboard global date filters. Defaults to CreationTime when omitted or null." }, "filter": { "oneOf": [ diff --git a/schemas/low-code/definitions/dashboard-visualization-descriptor.schema.json b/schemas/low-code/definitions/dashboard-visualization-descriptor.schema.json index 5634498f74..483b6dce9e 100644 --- a/schemas/low-code/definitions/dashboard-visualization-descriptor.schema.json +++ b/schemas/low-code/definitions/dashboard-visualization-descriptor.schema.json @@ -44,8 +44,8 @@ "description": "Entity this visualization sources data from. Required for chart and list visualizations; numberContainer items define their own entityName." }, "globalDateFilterProperty": { - "type": "string", - "description": "Date/DateTime property used to apply dashboard global date filters to this visualization. Defaults to CreationTime when omitted." + "type": ["string", "null"], + "description": "Date/DateTime property used to apply dashboard global date filters to this visualization. Defaults to CreationTime when omitted or null." }, "filter": { "oneOf": [ diff --git a/schemas/low-code/definitions/descriptor-metadata.schema.json b/schemas/low-code/definitions/descriptor-metadata.schema.json new file mode 100644 index 0000000000..e843518f41 --- /dev/null +++ b/schemas/low-code/definitions/descriptor-metadata.schema.json @@ -0,0 +1,17 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "descriptor-metadata.schema.json", + "title": "DescriptorMetadata", + "description": "Free-form string key/value metadata attached to a descriptor. Keys are compared case-insensitively and must be unique; values must be strings or null.", + "markdownDescription": "AI guidance: use `metadata` for tooling or documentation annotations such as `owner`, `generatedBy`, or `ticket`. The runtime does not interpret metadata; it is merged across model layers and preserved by the designer. Do not store structured data here; values must be plain strings or null.", + "type": "object", + "propertyNames": { + "minLength": 1 + }, + "additionalProperties": { + "type": ["string", "null"] + }, + "examples": [ + { "owner": "crm-team", "generatedBy": "abp-studio" } + ] +} diff --git a/schemas/low-code/definitions/endpoint-descriptor.schema.json b/schemas/low-code/definitions/endpoint-descriptor.schema.json index cdbfaa18fb..d5f112252e 100644 --- a/schemas/low-code/definitions/endpoint-descriptor.schema.json +++ b/schemas/low-code/definitions/endpoint-descriptor.schema.json @@ -3,7 +3,7 @@ "$id": "endpoint-descriptor.schema.json", "title": "Custom Endpoint Descriptor", "description": "Defines a custom HTTP endpoint that executes server-side JavaScript code.", - "markdownDescription": "AI guidance: use custom endpoints for model-owned actions and lightweight APIs. `name` must be unique. `route` should start with `/api/` and must not conflict with another route/method. Use `{id}` style path parameters when needed. Scripts can access request data through the endpoint context and return HTTP results with helpers such as `context.ok(value)`, `context.created(value)`, and `context.noContent()` where available. Require authentication by default and add `requiredPermissions` for protected operations.", + "markdownDescription": "AI guidance: use custom endpoints for model-owned actions and lightweight APIs. `name` must be unique within its app. `route` should start with `/api/` and must not conflict with another route/method. Use `{id}` style path parameters when needed. With `routeScope: \"app\"` the route is published beneath `/api/low-code/apps//endpoints` instead of verbatim. Scripts can access request data through the endpoint context and return HTTP results with helpers such as `context.ok(value)`, `context.created(value)`, and `context.noContent()` where available. Require authentication by default; add `requiredPermissions` for protected operations or set `useResourceAuthorization: true` to authorize per endpoint name through ABP resource permissions.", "type": "object", "properties": { "$schema": { @@ -15,15 +15,27 @@ "description": "Unique endpoint identifier used by designer/model health. Prefer PascalCase or kebab-case, for example 'SearchCustomers'.", "minLength": 1 }, + "app": { + "type": "string", + "description": "Name of the low-code app that owns this endpoint. Omit for the default app. Must match an apps[].name.", + "minLength": 1, + "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" + }, "route": { "type": "string", - "description": "URL route pattern. Must start with '/' and should use an application-specific prefix such as '/api/low-code/events/{id}'. Route parameters use ASP.NET style braces, for example '{id}'.", + "description": "URL route pattern. Must start with '/' and should use an application-specific prefix such as '/api/low-code/events/{id}'. Route parameters use ASP.NET style braces, for example '{id}'. With routeScope 'app', this is appended to the app endpoint prefix.", "minLength": 1, "pattern": "^/" }, + "routeScope": { + "type": "string", + "description": "'global' publishes route unchanged. 'app' publishes it beneath '/api/low-code/apps//endpoints'. Does not change ownership, authentication, or permissions.", + "enum": ["global", "app"], + "default": "global" + }, "method": { "type": "string", - "description": "HTTP method. GET should be read-only; POST/PUT/PATCH/DELETE may mutate state.", + "description": "HTTP method. GET should be read-only; POST/PUT/PATCH/DELETE may mutate state. Values are normalized to upper-case.", "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"], "default": "GET" }, @@ -37,9 +49,14 @@ "description": "Whether authentication is required. Keep true unless this endpoint is intentionally public.", "default": true }, + "useResourceAuthorization": { + "type": "boolean", + "description": "When true, access is granted per endpoint name through the generated ABP resource permission for this endpoint, in addition to requiredPermissions.", + "default": false + }, "requiredPermissions": { "type": "array", - "description": "Permission names required to access the endpoint. Checked only when authentication is required. Values should reference custom permissions or known static permissions.", + "description": "Permission names required to access the endpoint. Permission checks imply authorization even when requireAuthentication is false. Values should reference custom permissions or known static permissions.", "items": { "type": "string" } @@ -47,9 +64,25 @@ "description": { "type": "string", "description": "Optional human-readable description for designer documentation and model health context." + }, + "extendsLowerLayer": { + "type": "boolean", + "description": "When true, this descriptor overrides selected fields of an endpoint with the same name defined in a lower model layer; route and javascript become optional.", + "default": false + }, + "metadata": { + "$ref": "descriptor-metadata.schema.json" } }, - "required": ["name", "route", "javascript"], + "required": ["name"], + "if": { + "properties": { "extendsLowerLayer": { "const": true } }, + "required": ["extendsLowerLayer"] + }, + "then": {}, + "else": { + "required": ["route", "javascript"] + }, "additionalProperties": false, "examples": [ { @@ -59,6 +92,15 @@ "requireAuthentication": true, "requiredPermissions": ["Acme.Customers.View"], "javascript": "var q = context.request.query.q || ''; var table = await db.query('Acme.Crm.Customer'); var rows = await table.where(c => c.Name.toLowerCase().includes(q.toLowerCase())).take(10).toList(); return context.ok(rows);" + }, + { + "name": "GetPipelineSummary", + "app": "crm", + "route": "/pipeline/summary", + "routeScope": "app", + "method": "GET", + "useResourceAuthorization": true, + "javascript": "return context.ok({ generatedAt: new Date().toISOString() });" } ] } diff --git a/schemas/low-code/definitions/entity-cross-field-validation-descriptor.schema.json b/schemas/low-code/definitions/entity-cross-field-validation-descriptor.schema.json index 5fff4ea579..9693bf1192 100644 --- a/schemas/low-code/definitions/entity-cross-field-validation-descriptor.schema.json +++ b/schemas/low-code/definitions/entity-cross-field-validation-descriptor.schema.json @@ -29,8 +29,8 @@ "minLength": 1 }, "message": { - "type": "string", - "description": "Optional custom validation message" + "type": ["string", "null"], + "description": "Optional custom validation message. Omit or null to use the default localized message." } }, "required": ["propertyName", "operator", "otherPropertyName"], diff --git a/schemas/low-code/definitions/entity-descriptor.schema.json b/schemas/low-code/definitions/entity-descriptor.schema.json index 175966db3a..d5a181f03e 100644 --- a/schemas/low-code/definitions/entity-descriptor.schema.json +++ b/schemas/low-code/definitions/entity-descriptor.schema.json @@ -3,7 +3,7 @@ "$id": "entity-descriptor.schema.json", "title": "EntityDescriptor", "description": "Describes a dynamic entity. An entity is the runtime data model: it defines a table-like aggregate, its properties, validations, parent-child relation, attachment support, and create/update/delete interceptors.", - "markdownDescription": "AI guidance: create one entity per aggregate/root concept. Use a stable namespace-style `name` such as `Acme.Crm.Customer`; this name is referenced by pages, forms, foreign keys, dashboards, scripts, and permissions. Put user-facing labels in `displayName`; choose `displayProperty` as a short string property used by lookups. Use `parent` only for child/detail entities that belong to a parent record.", + "markdownDescription": "AI guidance: create one entity per aggregate/root concept. Use a stable namespace-style `name` such as `Acme.Crm.Customer`; this name is referenced by pages, forms, foreign keys, dashboards, scripts, and permissions. Put user-facing labels in `displayName`; choose `displayProperty` as a short string property used by lookups. Use `parent` only for child/detail entities that belong to a parent record. Set `app` only when the entity belongs to a non-default low-code app. Reverse relationship access is configured on page `relationships`, not on the entity.", "type": "object", "properties": { "$schema": { @@ -12,23 +12,45 @@ }, "name": { "type": "string", - "description": "Stable full name of the entity, usually Namespace.Module.EntityName (for example 'Acme.Crm.Customer'). Must be unique across all model layers. Do not rename after data exists unless a migration/rename flow is intended.", + "description": "Stable full name of the entity, usually Namespace.Module.EntityName (for example 'Acme.Crm.Customer'). Must be unique within its app across all model layers. Do not rename after data exists unless a migration/rename flow is intended.", "minLength": 1 }, + "app": { + "type": "string", + "description": "Name of the low-code app that owns this entity. Omit for the default app. Must match an apps[].name; app-scoped entities are addressed at runtime as ':'.", + "minLength": 1, + "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" + }, "displayName": { "type": "string", "description": "Default plural/screen label for this entity (for example 'Customers'). Page menu titles are configured separately on page descriptors.", "minLength": 1 }, + "description": { + "type": "string", + "description": "Optional description for designer documentation and model health context." + }, + "order": { + "type": "integer", + "description": "Optional sort order used by the designer and generated menus/lists when listing entities. Lower values appear first." + }, "displayProperty": { "type": "string", - "description": "Property name used when another entity references this entity in a lookup/autocomplete. Prefer a required string property such as 'Name', 'Title', or 'Code'." + "description": "Property name used when another entity references this entity in a lookup/autocomplete. Prefer a required string property such as 'Name', 'Title', or 'Code'. Defaults to 'Id' when omitted." }, "parent": { "type": "string", - "description": "Full name of the parent entity for parent-child/detail entities. When set, records of this entity are scoped under the parent and should include an FK property to the parent.", + "description": "Full name of the parent entity for parent-child/detail entities. When set, records of this entity are scoped under the parent and the runtime adds a 'Id' foreign key property automatically.", "minLength": 1 }, + "extendsLowerLayer": { + "type": "boolean", + "description": "When true, this descriptor extends an entity with the same name defined in a lower model layer (for example code-first attributes or the defaults layer) instead of defining a new entity. Only the overridden fields need to be present.", + "default": false + }, + "metadata": { + "$ref": "descriptor-metadata.schema.json" + }, "attachments": { "$ref": "entity-attachment-descriptor.schema.json", "description": "Record-level attachment settings. Use this for multiple arbitrary files attached to a record; use File/Image properties for first-class file fields." @@ -64,7 +86,19 @@ "displayProperty": "Name", "properties": [ { "name": "Name", "type": "string", "isRequired": true }, - { "name": "Email", "type": "string", "validators": [{ "type": "email" }] } + { "name": "Email", "type": "string", "validators": [{ "type": "email" }] }, + { "name": "OrderCount", "type": "long", "rollup": { "sourceEntityName": "Acme.Crm.Order", "foreignKeyPropertyName": "CustomerId", "operation": "count" } } + ] + }, + { + "name": "Acme.Crm.Contact", + "app": "crm", + "displayName": "Contacts", + "displayProperty": "FullName", + "properties": [ + { "name": "FirstName", "type": "string", "isRequired": true }, + { "name": "LastName", "type": "string", "isRequired": true }, + { "name": "FullName", "type": "string", "formula": { "expression": "FirstName & \" \" & LastName", "resultType": "string" } } ] } ] diff --git a/schemas/low-code/definitions/entity-formula-descriptor.schema.json b/schemas/low-code/definitions/entity-formula-descriptor.schema.json new file mode 100644 index 0000000000..ecb58bc13b --- /dev/null +++ b/schemas/low-code/definitions/entity-formula-descriptor.schema.json @@ -0,0 +1,25 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "entity-formula-descriptor.schema.json", + "title": "EntityFormulaDescriptor", + "description": "Defines a virtual calculated property evaluated from other properties of the same record with the Low-Code Expression Language.", + "markdownDescription": "AI guidance: a formula property is read-only and never stored: the runtime forces `isMappedToDbField: false`, `allowSetByClients: false`, `isRequired: false`, `isUnique: false`, and clears `defaultValue`. `expression` uses the Low-Code Expression Language (for example `If(Quantity = 0, 0, Total / Quantity)` or `FirstName & \" \" & LastName`) and may reference other scalar, formula, or rollup properties of the entity. `resultType` must match the property `type`. Formulas cannot be combined with `foreignKey`, `rollup`, or `collection`.", + "type": "object", + "properties": { + "expression": { + "type": "string", + "description": "Low-Code Expression Language expression evaluated against the current record, for example 'Round(UnitPrice * Quantity, 2)'.", + "minLength": 1 + }, + "resultType": { + "$ref": "entity-property-type.schema.json", + "description": "Type of the evaluated value. Should match the owning property type." + } + }, + "required": ["expression", "resultType"], + "additionalProperties": false, + "examples": [ + { "expression": "Round(UnitPrice * Quantity, 2)", "resultType": "decimal" }, + { "expression": "FirstName & \" \" & LastName", "resultType": "string" } + ] +} diff --git a/schemas/low-code/definitions/entity-property-collection-descriptor.schema.json b/schemas/low-code/definitions/entity-property-collection-descriptor.schema.json new file mode 100644 index 0000000000..7ae09b5751 --- /dev/null +++ b/schemas/low-code/definitions/entity-property-collection-descriptor.schema.json @@ -0,0 +1,25 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "entity-property-collection-descriptor.schema.json", + "title": "EntityPropertyCollectionDescriptor", + "description": "Turns a scalar entity property into an ordered primitive collection (a list of values of the property type).", + "markdownDescription": "AI guidance: add `collection` to store a list of values such as tags, scores, enum flags, or multiple files/images. The element type is the property `type`; supported element types are string, int, long, decimal, money, datetime, date, time, boolean, guid, enum, file, and image. Collections are stored in normalized collection tables, so `isMappedToDbField` does not apply. `uniqueItems` must be decided explicitly. A collection cannot be combined with `foreignKey`, `formula`, or `rollup`.", + "type": "object", + "properties": { + "maxCount": { + "type": ["integer", "null"], + "description": "Maximum number of items allowed. Omit or null for no limit.", + "minimum": 1 + }, + "uniqueItems": { + "type": "boolean", + "description": "Whether duplicate values are rejected. Required; choose true for tag-like lists and false for repeatable values." + } + }, + "required": ["uniqueItems"], + "additionalProperties": false, + "examples": [ + { "uniqueItems": true }, + { "maxCount": 10, "uniqueItems": false } + ] +} diff --git a/schemas/low-code/definitions/entity-property-descriptor.schema.json b/schemas/low-code/definitions/entity-property-descriptor.schema.json index ed4cc8da06..263f9b827b 100644 --- a/schemas/low-code/definitions/entity-property-descriptor.schema.json +++ b/schemas/low-code/definitions/entity-property-descriptor.schema.json @@ -2,8 +2,8 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "entity-property-descriptor.schema.json", "title": "EntityPropertyDescriptor", - "description": "Describes one dynamic entity property. Properties define persisted data fields, enum fields, foreign keys, upload fields, server-only fields, defaults, uniqueness, and validators.", - "markdownDescription": "AI guidance: use PascalCase property names. Use `type` for primitive fields, `type: \"enum\"` with `enumType` for enum fields, and a `foreignKey` object for lookup fields. FK property names should normally end with `Id`. Keep sensitive values `serverOnly: true`. Do not add legacy UI configuration here; page columns/filters and form fields own UI behavior.", + "description": "Describes one dynamic entity property. Properties define persisted data fields, enum fields, foreign keys, upload fields, primitive collections, calculated formulas, rollups, server-only fields, defaults, uniqueness, and validators.", + "markdownDescription": "AI guidance: use PascalCase property names. Use `type` for primitive fields, `type: \"enum\"` with `enumType` for enum fields, and a `foreignKey` object for lookup fields. FK property names should normally end with `Id`. Add `collection` for ordered value lists, `formula` for virtual calculated values, and `rollup` for aggregates over related records; these three and `foreignKey` are mutually exclusive. Keep sensitive values `serverOnly: true`. Do not add legacy UI configuration here; page columns/filters and form fields own UI behavior.", "type": "object", "properties": { "name": { @@ -13,7 +13,7 @@ }, "type": { "$ref": "entity-property-type.schema.json", - "description": "Primitive or special property type. If omitted, runtime treats the property as string. Use 'enum' only with enumType; use 'file'/'image' for first-class upload fields." + "description": "Primitive or special property type. If omitted, runtime treats the property as string (or enum when enumType is set). Use 'enum' only with enumType; use 'file'/'image' for first-class upload fields." }, "displayName": { "type": "string", @@ -22,11 +22,11 @@ }, "enumType": { "type": "string", - "description": "Name of a JSON-defined enum from top-level enums or a full type name for code enums. Required when type is 'enum'." + "description": "Name of a JSON-defined enum from the enums collection or a full type name for code enums. Required when type is 'enum'; setting it without type implies 'enum'." }, "allowSetByClients": { "type": "boolean", - "description": "Controls whether create/update clients may set the property. Use false for server-computed or protected fields that can still be returned to clients." + "description": "Controls whether create/update clients may set the property. Use false for server-computed or protected fields that can still be returned to clients. Forced to false for formula and rollup properties." }, "serverOnly": { "type": "boolean", @@ -34,11 +34,11 @@ }, "isMappedToDbField": { "type": "boolean", - "description": "Whether this property is mapped to a database column. Keep true or omit for normal persisted fields. Use false for computed/transient fields supplied by scripts or backend logic." + "description": "Whether this property uses a dedicated physical column. Omitted/false scalar properties use the configured dynamic data storage (JSON by default). Forced to false for formula and rollup properties; not applicable to collections." }, "defaultValue": { "type": ["string", "null"], - "description": "Default value for new records. Stored as a string in descriptor JSON and converted to the declared property type at runtime. Examples: '0' for int/enum, 'true' for boolean, '2026-05-18T09:00:00Z' for datetime." + "description": "Default value for new records. Stored as a string in descriptor JSON and converted to the declared property type at runtime. Examples: '0' for int/enum, 'true' for boolean, '2026-05-18T09:00:00Z' for datetime. Ignored for formula and rollup properties." }, "isUnique": { "type": "boolean", @@ -77,9 +77,31 @@ }, "imageResizeMode": { "type": "string", - "description": "How uploaded images should be resized when image dimensions are configured. 'fit' preserves the full image inside the bounds; 'fill' crops/fills the target bounds.", + "description": "How uploaded images should be resized when image dimensions are configured. 'fit' preserves the full image inside the bounds; 'fill' crops/fills the target bounds (requires both imageMaxWidth and imageMaxHeight).", "enum": ["fit", "fill"] }, + "decimalPlaces": { + "type": "integer", + "description": "Decimal scale for 'decimal' and 'money' properties. Controls storage precision and default UI formatting. Defaults to 2 when omitted.", + "minimum": 0 + }, + "currencySymbol": { + "type": "string", + "description": "Optional currency symbol or code displayed by money-aware controls for 'money' properties, for example '$' or 'EUR'.", + "minLength": 1 + }, + "collection": { + "$ref": "entity-property-collection-descriptor.schema.json", + "description": "Turns this property into an ordered list of values of the declared type. Cannot be combined with foreignKey, formula, or rollup." + }, + "formula": { + "$ref": "entity-formula-descriptor.schema.json", + "description": "Virtual calculated value evaluated from other properties of the same record. Makes the property read-only and non-persisted." + }, + "rollup": { + "$ref": "entity-rollup-descriptor.schema.json", + "description": "Virtual aggregate over related records that reference this record. Makes the property read-only and non-persisted." + }, "validators": { "type": "array", "description": "Backend/UI validators for this property. Use required, length, range, pattern, email, phone, url, or creditCard as appropriate. Duplicate required can be omitted when isRequired is true unless a custom message is needed.", @@ -91,11 +113,23 @@ "required": [ "name" ], + "allOf": [ + { "not": { "required": ["formula", "rollup"] } }, + { "not": { "required": ["formula", "foreignKey"] } }, + { "not": { "required": ["rollup", "foreignKey"] } }, + { "not": { "required": ["collection", "foreignKey"] } }, + { "not": { "required": ["collection", "formula"] } }, + { "not": { "required": ["collection", "rollup"] } } + ], "additionalProperties": false, "examples": [ { "name": "Name", "type": "string", "isRequired": true, "validators": [{ "type": "maxLength", "length": 128 }] }, { "name": "Status", "type": "enum", "enumType": "Acme.Events.EventStatus", "defaultValue": "0" }, { "name": "CustomerId", "foreignKey": { "entityName": "Acme.Crm.Customer", "displayPropertyName": "Name" } }, - { "name": "CoverImage", "type": "image", "fileAllowedContentTypes": ["image/*"], "fileMaxSizeBytes": 5242880, "imageResizeMode": "fit" } + { "name": "CoverImage", "type": "image", "fileAllowedContentTypes": ["image/*"], "fileMaxSizeBytes": 5242880, "imageResizeMode": "fit" }, + { "name": "Price", "type": "money", "decimalPlaces": 2, "currencySymbol": "$" }, + { "name": "Tags", "type": "string", "collection": { "maxCount": 20, "uniqueItems": true } }, + { "name": "Total", "type": "decimal", "formula": { "expression": "Round(UnitPrice * Quantity, 2)", "resultType": "decimal" } }, + { "name": "OrderCount", "type": "long", "rollup": { "sourceEntityName": "Acme.Crm.Order", "foreignKeyPropertyName": "CustomerId", "operation": "count" } } ] } diff --git a/schemas/low-code/definitions/entity-rollup-descriptor.schema.json b/schemas/low-code/definitions/entity-rollup-descriptor.schema.json new file mode 100644 index 0000000000..aed0d646fa --- /dev/null +++ b/schemas/low-code/definitions/entity-rollup-descriptor.schema.json @@ -0,0 +1,43 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "entity-rollup-descriptor.schema.json", + "title": "EntityRollupDescriptor", + "description": "Defines a virtual rollup property that aggregates records of another entity whose foreign key points back to the owning record.", + "markdownDescription": "AI guidance: use rollups for counts and sums over child/related records, for example the number of orders per customer or the total amount of order lines per order. `sourceEntityName` is the entity being aggregated and `foreignKeyPropertyName` is the FK property on that entity that references the owning entity. `count` needs no `valuePropertyName`; `sum`, `average`, `min`, and `max` require a numeric/date `valuePropertyName` on the source entity. Rollup properties are read-only and never stored: the runtime forces `isMappedToDbField: false`, `allowSetByClients: false`, and clears required/unique/default settings. Rollups cannot be combined with `foreignKey`, `formula`, or `collection`.", + "type": "object", + "properties": { + "sourceEntityName": { + "type": "string", + "description": "Full name of the entity whose records are aggregated, for example 'Acme.Orders.Order'.", + "minLength": 1 + }, + "foreignKeyPropertyName": { + "type": "string", + "description": "Foreign key property on sourceEntityName that references the owning entity, for example 'CustomerId'.", + "minLength": 1 + }, + "valuePropertyName": { + "type": ["string", "null"], + "description": "Property on sourceEntityName to aggregate. Required for sum, average, min, and max; omit for count." + }, + "operation": { + "type": "string", + "description": "Aggregation operation. Prefer lower-case values; PascalCase aliases are accepted.", + "enum": ["count", "Count", "sum", "Sum", "average", "Average", "min", "Min", "max", "Max"] + } + }, + "required": ["sourceEntityName", "foreignKeyPropertyName", "operation"], + "if": { + "properties": { "operation": { "enum": ["sum", "Sum", "average", "Average", "min", "Min", "max", "Max"] } }, + "required": ["operation"] + }, + "then": { + "required": ["valuePropertyName"], + "properties": { "valuePropertyName": { "type": "string", "minLength": 1 } } + }, + "additionalProperties": false, + "examples": [ + { "sourceEntityName": "Acme.Orders.Order", "foreignKeyPropertyName": "CustomerId", "operation": "count" }, + { "sourceEntityName": "Acme.Orders.OrderLine", "foreignKeyPropertyName": "OrderId", "valuePropertyName": "LineTotal", "operation": "sum" } + ] +} diff --git a/schemas/low-code/definitions/enum-descriptor.schema.json b/schemas/low-code/definitions/enum-descriptor.schema.json index 4a70d5c8f0..a5415640be 100644 --- a/schemas/low-code/definitions/enum-descriptor.schema.json +++ b/schemas/low-code/definitions/enum-descriptor.schema.json @@ -1,56 +1,103 @@ { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "enum-descriptor.schema.json", - "title": "EnumDescriptor", - "description": "Describes an integer-backed enum definition for use in entity properties and select/kanban UI.", - "markdownDescription": "AI guidance: define enums before entity properties that reference them. Use a stable namespace-style `name` such as `Acme.Events.EventStatus`. Each value name should be PascalCase and unique within the enum. Use explicit integer `value`s for stable persistence; do not reorder or renumber after data exists.", - "type": "object", - "properties": { - "$schema": { - "type": "string", - "description": "Optional schema reference used when this descriptor is stored as a model descriptor file." - }, - "name": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "enum-descriptor.schema.json", + "title": "EnumDescriptor", + "description": "Describes an integer-backed enum definition for use in entity properties and select/kanban UI, including optional per-value display metadata.", + "markdownDescription": "AI guidance: define enums before entity properties that reference them. Use a stable namespace-style `name` such as `Acme.Events.EventStatus`. Each value name should be PascalCase and unique within the enum. Use explicit integer `value`s for stable persistence; do not reorder or renumber after data exists. Add `displayName`, `presentation`, `color`, and `icon` on values when pages should render badges or icons by default; pages can still override them with `enumPresentations`.", + "type": "object", + "properties": { + "$schema": { + "type": "string", + "description": "Optional schema reference used when this descriptor is stored as a model descriptor file." + }, + "name": { + "type": "string", + "description": "Stable unique enum name. Use a namespace-style name if the enum belongs to a module/domain, for example 'Acme.Events.EventStatus'.", + "minLength": 1 + }, + "app": { + "type": "string", + "description": "Name of the low-code app that owns this enum. Omit for the default app. Must match an apps[].name.", + "minLength": 1, + "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" + }, + "displayName": { + "type": "string", + "description": "User-facing enum title used by the designer, for example 'Event Status'.", + "minLength": 1 + }, + "order": { + "type": "integer", + "description": "Optional sort order used when listing enums in the designer. Lower values appear first." + }, + "extendsLowerLayer": { + "type": "boolean", + "description": "When true, this descriptor extends an enum with the same name defined in a lower model layer (for example a code enum) by adding values or display metadata instead of defining a new enum.", + "default": false + }, + "metadata": { + "$ref": "descriptor-metadata.schema.json" + }, + "values": { + "type": "array", + "description": "Ordered list of integer-backed enum values. Values are stored as integers; names are used for display and model readability.", + "items": { + "type": "object", + "properties": { + "name": { "type": "string", - "description": "Stable unique enum name. Use a namespace-style name if the enum belongs to a module/domain, for example 'Acme.Events.EventStatus'.", + "description": "PascalCase enum value name, for example 'Draft', 'Scheduled', or 'Completed'.", "minLength": 1 + }, + "value": { + "type": "integer", + "description": "Stable integer value. Prefer explicit values starting at 0 so generated descriptor JSON is deterministic. When omitted, the previous value plus one is assigned." + }, + "displayName": { + "type": ["string", "null"], + "description": "User-facing label for this value, for example 'In Progress'. Defaults to the value name." + }, + "presentation": { + "oneOf": [ + { "$ref": "enum-value-presentation.schema.json" }, + { "type": "null" } + ], + "description": "Default runtime presentation for this value: text, badge, or iconOnly." + }, + "color": { + "type": ["string", "null"], + "description": "Default badge color for this value, for example '#F59E0B'." + }, + "icon": { + "oneOf": [ + { "$ref": "presentation-icon-reference.schema.json" }, + { "type": "null" } + ], + "description": "Default icon for this value, used by badge and iconOnly presentations." + } }, - "values": { - "type": "array", - "description": "Ordered list of integer-backed enum values. Values are stored as integers; names are used for display and model readability.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "PascalCase enum value name, for example 'Draft', 'Scheduled', or 'Completed'." - }, - "value": { - "type": "integer", - "description": "Stable integer value. Prefer explicit values starting at 0 so generated descriptor JSON is deterministic." - } - }, - "required": [ - "name" - ], - "additionalProperties": false - }, - "minItems": 1 - } - }, - "required": [ - "name", - "values" - ], - "additionalProperties": false, - "examples": [ - { - "name": "Acme.Events.EventStatus", - "values": [ - { "name": "Draft", "value": 0 }, - { "name": "Scheduled", "value": 1 }, - { "name": "Completed", "value": 2 } - ] - } - ] + "required": [ + "name" + ], + "additionalProperties": false + }, + "minItems": 1 + } + }, + "required": [ + "name", + "values" + ], + "additionalProperties": false, + "examples": [ + { + "name": "Acme.Events.EventStatus", + "displayName": "Event Status", + "values": [ + { "name": "Draft", "value": 0 }, + { "name": "Scheduled", "value": 1, "displayName": "Scheduled", "presentation": "badge", "color": "#2563EB" }, + { "name": "Completed", "value": 2, "presentation": "badge", "color": "#16A34A", "icon": { "kind": "class", "value": "fa-solid fa-check" } } + ] + } + ] } diff --git a/schemas/low-code/definitions/enum-value-presentation.schema.json b/schemas/low-code/definitions/enum-value-presentation.schema.json new file mode 100644 index 0000000000..c3f13476b9 --- /dev/null +++ b/schemas/low-code/definitions/enum-value-presentation.schema.json @@ -0,0 +1,17 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "enum-value-presentation.schema.json", + "title": "EnumValuePresentation", + "description": "How an enum value is rendered by runtime pages. Prefer lower-case values in descriptor JSON; PascalCase aliases are accepted for compatibility.", + "markdownDescription": "`text` renders the display name as plain text. `badge` renders a colored badge using `color`. `iconOnly` renders only the `icon` (with the display name as tooltip).", + "type": "string", + "enum": ["text", "Text", "badge", "Badge", "iconOnly", "IconOnly"], + "enumDescriptions": [ + "Plain text display name.", + "Plain text display name.", + "Colored badge.", + "Colored badge.", + "Icon only, display name as tooltip.", + "Icon only, display name as tooltip." + ] +} diff --git a/schemas/low-code/definitions/foreign-key-descriptor.schema.json b/schemas/low-code/definitions/foreign-key-descriptor.schema.json index 358bdee4ee..b27a7fcca2 100644 --- a/schemas/low-code/definitions/foreign-key-descriptor.schema.json +++ b/schemas/low-code/definitions/foreign-key-descriptor.schema.json @@ -3,7 +3,7 @@ "$id": "foreign-key-descriptor.schema.json", "title": "ForeignKeyDescriptor", "description": "Describes a foreign key/lookup relationship from the owning entity property to another entity or reference entity.", - "markdownDescription": "AI guidance: put `foreignKey` on the property that stores the related record id. The property name should usually end with `Id`, for example `CustomerId`. `entityName` must match a model entity name or a registered code/reference entity such as `Volo.Abp.Identity.IdentityUser`. Use `displayPropertyName` when the target display field is not obvious. Use `dependsOn` for cascading dropdowns such as City filtered by Country. Use `access` only for reverse access from the referenced entity side: `none`, `view`, or `edit`. Do not use `lookup` as `access`; lookup is a form field/control type.", + "markdownDescription": "AI guidance: put `foreignKey` on the property that stores the related record id. The property name should usually end with `Id`, for example `CustomerId`. `entityName` must match a model entity name or a registered code/reference entity such as `Volo.Abp.Identity.IdentityUser`. Use `displayPropertyName` when the target display field is not obvious. Use `dependsOn` for cascading dropdowns such as City filtered by Country. Reverse access from the referenced entity side (showing or editing related records from the target page) is not configured here; define a `relationships[]` entry on the target entity's page descriptor instead. Do not use `lookup` here; lookup is a form field/control type.", "type": "object", "properties": { "entityName": { @@ -12,15 +12,8 @@ "minLength": 1 }, "displayPropertyName": { - "type": "string", - "description": "Property name to display from the related entity in lookups/autocomplete. Omit to use the target entity displayProperty.", - "minLength": 1 - }, - "access": { - "type": "string", - "description": "Access level for managing this relation from the referenced entity side. 'none' means no reverse access; 'view' allows the referenced entity page to show related records; 'edit' allows managing related records from the referenced side.", - "enum": ["none", "None", "view", "View", "edit", "Edit"], - "default": "none" + "type": ["string", "null"], + "description": "Property name to display from the related entity in lookups/autocomplete. Omit to use the target entity displayProperty." }, "dependsOn": { "type": "object", diff --git a/schemas/low-code/definitions/form-descriptor.schema.json b/schemas/low-code/definitions/form-descriptor.schema.json index 102193ee10..2db7ca64de 100644 --- a/schemas/low-code/definitions/form-descriptor.schema.json +++ b/schemas/low-code/definitions/form-descriptor.schema.json @@ -15,6 +15,12 @@ "description": "Stable unique form identifier. Prefer kebab-case, for example 'customer-form' or 'event-form'. Pages reference this value.", "minLength": 1 }, + "app": { + "type": "string", + "description": "Name of the low-code app that owns this form. Omit for the default app. Must match an apps[].name.", + "minLength": 1, + "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" + }, "entityName": { "type": "string", "description": "Full name of the entity this form is bound to. Must match the page entityName that uses this form.", @@ -42,9 +48,25 @@ "items": { "$ref": "form-rule-descriptor.schema.json" } + }, + "extendsLowerLayer": { + "type": "boolean", + "description": "When true, this descriptor overrides selected fields of a form with the same name defined in a lower model layer; entityName, fields, and layout become optional.", + "default": false + }, + "metadata": { + "$ref": "descriptor-metadata.schema.json" } }, - "required": ["name", "entityName", "fields", "layout"], + "required": ["name"], + "if": { + "properties": { "extendsLowerLayer": { "const": true } }, + "required": ["extendsLowerLayer"] + }, + "then": {}, + "else": { + "required": ["entityName", "fields", "layout"] + }, "additionalProperties": false, "examples": [ { diff --git a/schemas/low-code/definitions/form-rule-descriptor.schema.json b/schemas/low-code/definitions/form-rule-descriptor.schema.json index f558b6bb1d..573fef07c0 100644 --- a/schemas/low-code/definitions/form-rule-descriptor.schema.json +++ b/schemas/low-code/definitions/form-rule-descriptor.schema.json @@ -43,6 +43,11 @@ "items": { "type": "object", "properties": { + "stableId": { + "type": "string", + "description": "Optional stable identifier assigned by the designer so model history and mutations can address this action. Omit in hand-written descriptors; the runtime generates one when missing.", + "minLength": 1 + }, "type": { "type": "string", "enum": ["hide", "show", "disable", "enable", "setValue"], diff --git a/schemas/low-code/definitions/page-backend-filter-expression.schema.json b/schemas/low-code/definitions/page-backend-filter-expression.schema.json new file mode 100644 index 0000000000..3aa1346f2c --- /dev/null +++ b/schemas/low-code/definitions/page-backend-filter-expression.schema.json @@ -0,0 +1,135 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "page-backend-filter-expression.schema.json", + "title": "PageBackendFilterExpression", + "description": "Server-enforced filter expression for an entity page. A single condition or a nested and/or group tree that is always applied by the backend and cannot be removed by the client.", + "markdownDescription": "AI guidance: use `backendFilter` for tenant, ownership, role, or workflow scoping that must not be user-editable. The root is either one condition or a group with `items`. Inside a group the first item has no `logic`; every following item must set `logic` to `and` or `or` to combine with the previous items. A condition names a `propertyName`, an explicit `operator` (never `default`), and exactly one value source: a static `value`, a `valueProvider` name registered in `AbpLowCodePageBackendFilterOptions` (for example `CurrentUserId`, `CurrentUserRoles`, `CurrentTenantId`), or a `javaScript` expression. `isNull`/`isNotNull` need no value; `hasValue` takes a boolean value; `between` takes two values; `in`/`notIn` take an array.", + "$defs": { + "logic": { + "type": "string", + "description": "How this item combines with the previous items of the same group.", + "enum": ["and", "And", "or", "Or"] + }, + "operator": { + "type": "string", + "description": "Filter operator. Must be explicit; 'default' is not allowed for backend filters. 'equals' is accepted as an alias of 'equal'.", + "enum": [ + "equal", + "equals", + "notEqual", + "contains", + "notContains", + "startsWith", + "endsWith", + "greaterThan", + "greaterThanOrEqual", + "lessThan", + "lessThanOrEqual", + "between", + "isNull", + "isNotNull", + "hasValue", + "in", + "notIn", + "thisWeek", + "lastWeek", + "thisMonth", + "lastMonth", + "thisYear", + "lastYear", + "today", + "beforeToday" + ] + }, + "conditionFields": { + "type": "object", + "properties": { + "logic": { "$ref": "#/$defs/logic" }, + "propertyName": { + "type": "string", + "description": "Property on the page entity to filter.", + "minLength": 1 + }, + "operator": { "$ref": "#/$defs/operator" }, + "value": { + "description": "Static filter value. Use an array for in/notIn, two values for between, and true/false for hasValue." + }, + "valueProvider": { + "type": "string", + "description": "Name of a registered backend filter value provider, for example 'CurrentUserId' or 'CurrentUserRoles'.", + "minLength": 1 + }, + "javaScript": { + "type": "string", + "description": "JavaScript expression evaluated on the server to produce the filter value.", + "minLength": 1 + } + }, + "required": ["propertyName"], + "additionalProperties": false, + "not": { + "anyOf": [ + { "required": ["value", "valueProvider"] }, + { "required": ["value", "javaScript"] }, + { "required": ["valueProvider", "javaScript"] } + ] + } + }, + "groupFields": { + "type": "object", + "properties": { + "logic": { "$ref": "#/$defs/logic" }, + "items": { + "type": "array", + "description": "Ordered child conditions and groups. The first item has no logic; later items require logic.", + "minItems": 1, + "prefixItems": [ + { + "allOf": [ + { "$ref": "#/$defs/node" }, + { "not": { "required": ["logic"] } } + ] + } + ], + "items": { + "allOf": [ + { "$ref": "#/$defs/node" }, + { "required": ["logic"] } + ] + } + } + }, + "required": ["items"], + "additionalProperties": false + }, + "node": { + "oneOf": [ + { "$ref": "#/$defs/conditionFields" }, + { "$ref": "#/$defs/groupFields" } + ] + } + }, + "allOf": [ + { "$ref": "#/$defs/node" }, + { "not": { "required": ["logic"] } } + ], + "examples": [ + { + "propertyName": "Status", + "operator": "equal", + "value": "Active" + }, + { + "items": [ + { "propertyName": "Status", "operator": "equal", "value": "Active" }, + { + "logic": "and", + "items": [ + { "propertyName": "CreatorId", "operator": "equal", "valueProvider": "CurrentUserId" }, + { "logic": "or", "propertyName": "AllowedRole", "operator": "in", "valueProvider": "CurrentUserRoles" } + ] + } + ] + } + ] +} diff --git a/schemas/low-code/definitions/page-column-descriptor.schema.json b/schemas/low-code/definitions/page-column-descriptor.schema.json index ebf0073e4a..422f39e123 100644 --- a/schemas/low-code/definitions/page-column-descriptor.schema.json +++ b/schemas/low-code/definitions/page-column-descriptor.schema.json @@ -3,12 +3,12 @@ "$id": "page-column-descriptor.schema.json", "title": "PageColumnDescriptor", "description": "Describes a property displayed by an entity page list, card, calendar event, or gallery item.", - "markdownDescription": "AI guidance: use page columns/card fields to control runtime page visibility. Each `propertyName` must match a property on the page entity. Keep this separate from entity property definitions so the same entity can have different views on different pages.", + "markdownDescription": "AI guidance: use page columns/card fields to control runtime page visibility. Each `propertyName` must match a property on the page entity or a dot-separated related path such as `CustomerId.Name`. Keep this separate from entity property definitions so the same entity can have different views on different pages. For boolean properties, `booleanPresentation` and `booleanValues` control how true/false/null render on this page.", "type": "object", "properties": { "propertyName": { "type": "string", - "description": "Property displayed by this column/card field. Must match a property on the page entityName.", + "description": "Property displayed by this column/card field. Must match a property on the page entityName or a related path such as 'CustomerId.CountryId.Name'.", "minLength": 1 }, "label": { @@ -30,6 +30,38 @@ "description": "Optional CSS width for tabular columns, for example '160px', '12rem', or '20%'.", "minLength": 1 }, + "booleanPresentation": { + "oneOf": [ + { "$ref": "boolean-value-presentation.schema.json" }, + { "type": "null" } + ], + "description": "How a boolean property is rendered on this page: text, checkbox, badge, or iconOnly. Only meaningful for boolean properties." + }, + "booleanValues": { + "type": ["object", "null"], + "description": "Per-state display metadata for boolean properties. Keys are 'true', 'false', and 'null'.", + "properties": { + "true": { + "oneOf": [ + { "$ref": "boolean-value-display-descriptor.schema.json" }, + { "type": "null" } + ] + }, + "false": { + "oneOf": [ + { "$ref": "boolean-value-display-descriptor.schema.json" }, + { "type": "null" } + ] + }, + "null": { + "oneOf": [ + { "$ref": "boolean-value-display-descriptor.schema.json" }, + { "type": "null" } + ] + } + }, + "additionalProperties": false + }, "visible": { "type": "boolean", "description": "Whether the field is visible by default on this page.", @@ -45,6 +77,16 @@ "additionalProperties": false, "examples": [ { "propertyName": "Title", "label": "Title", "order": 0, "exportOrder": 0, "width": "240px", "visible": true }, - { "propertyName": "InternalNotes", "visible": false, "exportable": false } + { "propertyName": "InternalNotes", "visible": false, "exportable": false }, + { "propertyName": "CustomerId.Name", "label": "Customer", "order": 1 }, + { + "propertyName": "IsActive", + "booleanPresentation": "badge", + "booleanValues": { + "true": { "displayName": "Active", "color": "#16A34A" }, + "false": { "displayName": "Inactive", "color": "#DC2626" }, + "null": { "displayName": "Not set", "color": "#6B7280" } + } + } ] } diff --git a/schemas/low-code/definitions/page-command-interceptor-descriptor.schema.json b/schemas/low-code/definitions/page-command-interceptor-descriptor.schema.json new file mode 100644 index 0000000000..bbcc6dfa9f --- /dev/null +++ b/schemas/low-code/definitions/page-command-interceptor-descriptor.schema.json @@ -0,0 +1,38 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "page-command-interceptor-descriptor.schema.json", + "title": "PageCommandInterceptorDescriptor", + "description": "Describes a JavaScript interceptor that runs for Create, Update, or Delete commands issued through a specific page, in addition to the entity-level interceptors.", + "markdownDescription": "AI guidance: use page interceptors when a rule applies only to commands sent from one page (for example a simplified public form) and entity interceptors for rules that must always apply. The script contract is the same as entity interceptors: inspect `context.commandArgs`, set `globalError` to block a Pre interceptor, and use host services on `context`. `entityExecutionOrder` controls how the page interceptor is ordered relative to the entity interceptor of the same command and phase: `entityFirst` (default), `pageFirst`, or `skipEntity` to suppress the entity interceptor for this page. It is ignored for `Replace` interceptors.", + "type": "object", + "properties": { + "commandName": { + "type": "string", + "description": "Entity command to intercept: Create, Update, Delete, or a registered custom command name.", + "minLength": 1 + }, + "type": { + "$ref": "interceptor-type.schema.json", + "description": "Whether the script runs before, after, or instead of the command." + }, + "javascript": { + "type": "string", + "description": "JavaScript code to execute. For Pre interceptors, set globalError to block the command." + }, + "entityExecutionOrder": { + "type": ["string", "null"], + "description": "Order relative to the entity interceptor with the same command and type. 'entityFirst' runs the entity interceptor first (default), 'pageFirst' runs this page interceptor first, 'skipEntity' skips the entity interceptor for this page. Not applicable to Replace interceptors.", + "enum": ["entityFirst", "EntityFirst", "pageFirst", "PageFirst", "skipEntity", "SkipEntity", null] + } + }, + "required": ["commandName", "type", "javascript"], + "additionalProperties": false, + "examples": [ + { + "commandName": "Create", + "type": "Pre", + "javascript": "if (!context.commandArgs.data['Source']) { context.commandArgs.data['Source'] = 'public-form'; }", + "entityExecutionOrder": "pageFirst" + } + ] +} diff --git a/schemas/low-code/definitions/page-descriptor.schema.json b/schemas/low-code/definitions/page-descriptor.schema.json index 475de3ad63..3d735d6288 100644 --- a/schemas/low-code/definitions/page-descriptor.schema.json +++ b/schemas/low-code/definitions/page-descriptor.schema.json @@ -3,7 +3,7 @@ "$id": "page-descriptor.schema.json", "title": "PageDescriptor", "description": "Describes a runtime UI page. Pages create menu items and choose how an entity or dashboard is rendered.", - "markdownDescription": "AI guidance: `name` is the stable route/menu key and should be URL-safe kebab-case (for example `customers` or `event-calendar`). `title` is user-facing. For entity pages, set `entityName` to an existing entity. Configure list/gallery/card visibility with `columns`, filtering with `filters`, and create/edit UI with form names. For `dashboard` pages, provide `dashboard` and omit entity-only fields unless intentionally supported by the runtime. Do not put page-only settings on entity properties.", + "markdownDescription": "AI guidance: `name` is the stable route/menu key and should be URL-safe kebab-case (for example `customers` or `event-calendar`). `title` is user-facing. For entity pages, set `entityName` to an existing entity. Configure list/gallery/card visibility with `columns`, filtering with `filters`, server-enforced scoping with `backendFilter`, related-record access with `relationships`, and create/edit UI with form names. Use `enumPresentations` to override enum display for this page only. For `dashboard` pages, provide `dashboard` and omit entity-only fields unless intentionally supported by the runtime. Do not put page-only settings on entity properties.", "type": "object", "properties": { "$schema": { @@ -12,9 +12,15 @@ }, "name": { "type": "string", - "description": "Stable URL-safe page identifier. Prefer kebab-case, for example 'customers', 'event-calendar', or 'sales-dashboard'. This becomes part of the runtime route and is referenced by saveSuccessPageName.", + "description": "Stable URL-safe page identifier. Prefer kebab-case, for example 'customers', 'event-calendar', or 'sales-dashboard'. This becomes part of the runtime route and is referenced by saveSuccessPageName and relationships.", "minLength": 1 }, + "app": { + "type": "string", + "description": "Name of the low-code app that owns this page. Omit for the default app. Must match an apps[].name.", + "minLength": 1, + "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" + }, "title": { "type": "string", "description": "Display title for the menu item and page header.", @@ -24,6 +30,11 @@ "type": "string", "description": "FontAwesome icon class for the menu item, for example 'fa-solid fa-users'." }, + "showInMenu": { + "type": "boolean", + "description": "Whether the page gets a menu item. Set false for pages that are only reached through relationships, saveSuccessPageName, or direct links.", + "default": true + }, "type": { "$ref": "page-type.schema.json" }, @@ -59,9 +70,14 @@ }, "galleryImageProperty": { "type": "string", - "description": "Optional Image property used as the cover image for gallery pages. The property should have entity property type image.", + "description": "Optional Image property used as the cover image for gallery pages. The property should have entity property type image; an image collection property is supported with galleryImagePresentation.", "minLength": 1 }, + "galleryImagePresentation": { + "type": ["string", "null"], + "description": "How gallery cards render galleryImageProperty. 'coverLightbox' shows a cover image that opens a lightbox; 'inlineSlider' shows an inline slider (useful for image collections). Omit for the default cover presentation.", + "enum": ["coverLightbox", "CoverLightbox", "inlineSlider", "InlineSlider", null] + }, "defaultSortProperty": { "type": "string", "description": "Optional property used as the default sorting field when the client does not send explicit sorting. Must reference a property on entityName.", @@ -73,29 +89,52 @@ "default": false }, "defaultFileExportMode": { - "type": "integer", - "enum": [0, 1, 2], - "description": "Default file export mode for file/image columns. 0 exports file names, 1 exports metadata columns, and 2 exports download-link columns." + "type": ["integer", "null"], + "enum": [0, 1, 2, 3, null], + "description": "Default spreadsheet output for file/image columns. 0 exports file names, 1 exports metadata columns, 2 exports temporary download-link columns, and 3 exports file names with download links." }, "allowFileBundleExport": { "type": "boolean", - "description": "Whether file bundle export is available for this page.", + "description": "Whether ZIP file bundle export is available for exportable file/image columns on this page.", + "default": true + }, + "importEnabled": { + "type": "boolean", + "description": "Whether the React runtime exposes guided Excel/CSV import for this page.", "default": true }, "columns": { "type": "array", - "description": "Page-owned column/card field configuration. Use for dataGrid, kanban card fields, calendar event fields, and gallery card fields. Each propertyName must reference a property on entityName.", + "description": "Page-owned column/card field configuration. Use for dataGrid, kanban card fields, calendar event fields, and gallery card fields. Each propertyName must reference a property on entityName or a dot-separated related path such as 'CustomerId.Name'.", "items": { "$ref": "page-column-descriptor.schema.json" } }, "filters": { "type": "array", - "description": "Page-owned filter configuration for filterable page types. Each propertyName must reference a property on entityName. Use this instead of legacy property-level UI filter settings.", + "description": "Page-owned filter configuration for filterable page types. Each propertyName must reference a property on entityName or a related path. Use this instead of legacy property-level UI filter settings.", "items": { "$ref": "page-filter-descriptor.schema.json" } }, + "enumPresentations": { + "type": "array", + "description": "Page-level overrides for enum value display (label, presentation, color, icon). Each propertyName may appear once.", + "items": { + "$ref": "page-enum-presentation-descriptor.schema.json" + } + }, + "relationships": { + "type": "array", + "description": "Reverse relationships shown from this page: records of other entities whose foreign key points at the page entity. Each id must be unique within the page.", + "items": { + "$ref": "page-relationship-descriptor.schema.json" + } + }, + "backendFilter": { + "$ref": "page-backend-filter-expression.schema.json", + "description": "Server-enforced filter expression that is always applied to this page's queries and cannot be removed by the client." + }, "order": { "type": "integer", "description": "Menu sort order (lower values appear first)", @@ -154,59 +193,82 @@ "permissionConfig": { "$ref": "page-permission-config.schema.json", "description": "Optional page operation permission overrides. Omit operations to use generated defaults." - } - }, - "required": ["name", "title", "type"], - "allOf": [ - { - "if": { - "properties": { "type": { "enum": ["dataGrid", "DataGrid"] } } - }, - "then": { - "required": ["entityName"] - } }, - { - "if": { - "properties": { "type": { "enum": ["kanban", "Kanban"] } } - }, - "then": { - "required": ["entityName", "groupByProperty"] + "interceptors": { + "type": "array", + "description": "Page-scoped Create/Update/Delete command interceptors that run for commands issued through this page, ordered relative to entity interceptors by entityExecutionOrder.", + "items": { + "$ref": "page-command-interceptor-descriptor.schema.json" } }, - { - "if": { - "properties": { "type": { "enum": ["calendar", "Calendar"] } } - }, - "then": { - "required": ["entityName", "calendarStartProperty"] - } + "extendsLowerLayer": { + "type": "boolean", + "description": "When true, this descriptor overrides selected fields of a page with the same name defined in a lower model layer; title, entityName, and type-specific required fields become optional.", + "default": false }, - { - "if": { - "properties": { "type": { "enum": ["gallery", "Gallery"] } } + "metadata": { + "$ref": "descriptor-metadata.schema.json" + } + }, + "required": ["name"], + "if": { + "properties": { "extendsLowerLayer": { "const": true } }, + "required": ["extendsLowerLayer"] + }, + "then": {}, + "else": { + "required": ["title", "type"], + "allOf": [ + { + "if": { + "properties": { "type": { "enum": ["dataGrid", "DataGrid"] } } + }, + "then": { + "required": ["entityName"] + } }, - "then": { - "required": ["entityName"] - } - }, - { - "if": { - "properties": { "type": { "enum": ["form", "Form"] } } + { + "if": { + "properties": { "type": { "enum": ["kanban", "Kanban"] } } + }, + "then": { + "required": ["entityName", "groupByProperty"] + } }, - "then": { - "required": ["entityName", "formName"] - } - }, - { - "if": { - "properties": { "type": { "enum": ["dashboard", "Dashboard"] } } + { + "if": { + "properties": { "type": { "enum": ["calendar", "Calendar"] } } + }, + "then": { + "required": ["entityName", "calendarStartProperty"] + } }, - "then": { - "required": ["dashboard"] + { + "if": { + "properties": { "type": { "enum": ["gallery", "Gallery"] } } + }, + "then": { + "required": ["entityName"] + } + }, + { + "if": { + "properties": { "type": { "enum": ["form", "Form"] } } + }, + "then": { + "required": ["entityName", "formName"] + } + }, + { + "if": { + "properties": { "type": { "enum": ["dashboard", "Dashboard"] } } + }, + "then": { + "required": ["dashboard"] + } } - } - ], + ] + }, "additionalProperties": false, "examples": [ { @@ -216,11 +278,19 @@ "entityName": "Acme.Events.Event", "columns": [ { "propertyName": "Title", "order": 0 }, - { "propertyName": "Status", "order": 1 } + { "propertyName": "Status", "order": 1 }, + { "propertyName": "IsPublished", "order": 2, "booleanPresentation": "badge", "booleanValues": { "true": { "displayName": "Published", "color": "#16A34A" }, "false": { "displayName": "Draft", "color": "#6B7280" } } } ], "filters": [ { "propertyName": "Title", "control": "text", "defaultOperator": "contains" } ], + "enumPresentations": [ + { "propertyName": "Status", "values": [{ "value": 2, "displayName": "Done", "presentation": "badge", "color": "#16A34A" }] } + ], + "relationships": [ + { "id": "event-sessions", "sourceEntityName": "Acme.Events.Session", "sourcePropertyName": "EventId", "access": "edit", "relatedPageMode": "generated", "createFormMode": "generated", "editFormMode": "generated" } + ], + "backendFilter": { "propertyName": "OrganizerId", "operator": "equal", "valueProvider": "CurrentUserId" }, "createFormName": "event-form", "editFormName": "event-form" }, @@ -230,7 +300,8 @@ "type": "calendar", "entityName": "Acme.Events.Event", "calendarStartProperty": "StartDate", - "calendarEndProperty": "EndDate" + "calendarEndProperty": "EndDate", + "showInMenu": false }, { "name": "event-dashboard", diff --git a/schemas/low-code/definitions/page-enum-presentation-descriptor.schema.json b/schemas/low-code/definitions/page-enum-presentation-descriptor.schema.json new file mode 100644 index 0000000000..66575ab354 --- /dev/null +++ b/schemas/low-code/definitions/page-enum-presentation-descriptor.schema.json @@ -0,0 +1,62 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "page-enum-presentation-descriptor.schema.json", + "title": "PageEnumPresentationDescriptor", + "description": "Page-level overrides for how the values of one enum property are displayed. The shared enum descriptor keeps the default presentation; this object changes it for a single page.", + "markdownDescription": "AI guidance: use page enum presentations when one page needs different labels, badges, colors, or icons for an enum property without changing the enum used by other pages. `propertyName` must be an enum property of the page entity and must be unique within `enumPresentations`. Each `values[]` item targets one integer enum `value`; only the fields present are overridden. A field set to `null` clears the value inherited from the enum or a lower model layer.", + "type": "object", + "properties": { + "propertyName": { + "type": "string", + "description": "Enum property on the page entity whose value presentation is overridden.", + "minLength": 1 + }, + "values": { + "type": "array", + "description": "Per-value overrides. Each integer value may appear once.", + "items": { + "type": "object", + "properties": { + "value": { + "type": "integer", + "description": "Integer enum value to override." + }, + "displayName": { + "type": ["string", "null"], + "description": "Page-specific label for this value." + }, + "presentation": { + "oneOf": [ + { "$ref": "enum-value-presentation.schema.json" }, + { "type": "null" } + ], + "description": "Page-specific presentation: text, badge, or iconOnly." + }, + "color": { + "type": ["string", "null"], + "description": "Page-specific badge color, for example '#F59E0B'." + }, + "icon": { + "oneOf": [ + { "$ref": "presentation-icon-reference.schema.json" }, + { "type": "null" } + ], + "description": "Page-specific icon." + } + }, + "required": ["value"], + "additionalProperties": false + } + } + }, + "required": ["propertyName"], + "additionalProperties": false, + "examples": [ + { + "propertyName": "Status", + "values": [ + { "value": 10, "displayName": "Awaiting review", "presentation": "badge", "color": "#F59E0B" } + ] + } + ] +} diff --git a/schemas/low-code/definitions/page-filter-descriptor.schema.json b/schemas/low-code/definitions/page-filter-descriptor.schema.json index ed63ba0653..688f74e13b 100644 --- a/schemas/low-code/definitions/page-filter-descriptor.schema.json +++ b/schemas/low-code/definitions/page-filter-descriptor.schema.json @@ -8,7 +8,7 @@ "properties": { "propertyName": { "type": "string", - "description": "Property filtered by this control. Must match a property on the page entityName.", + "description": "Property filtered by this control. Must match a property on the page entityName or a related path such as 'CustomerId.CountryId.Name'.", "minLength": 1 }, "label": { @@ -34,7 +34,7 @@ }, "defaultOperator": { "type": "string", - "description": "Default operator applied by this filter. Use 'contains' for text search, 'equal' for enum/FK exact matches, 'between' for ranges, and 'default' to let runtime choose.", + "description": "Default operator applied by this filter. Use 'contains' for text search, 'equal' for enum/FK exact matches, 'between' for ranges, 'hasValue' for presence (Yes/No/All) checks, relative-date operators such as 'thisMonth' or 'today' for date/datetime properties, and 'default' to let runtime choose.", "enum": [ "default", "equal", @@ -52,7 +52,15 @@ "isNull", "isNotNull", "in", - "notIn" + "notIn", + "thisWeek", + "lastWeek", + "thisMonth", + "lastMonth", + "thisYear", + "lastYear", + "today", + "beforeToday" ] }, "allowedOperators": { @@ -77,7 +85,15 @@ "isNull", "isNotNull", "in", - "notIn" + "notIn", + "thisWeek", + "lastWeek", + "thisMonth", + "lastMonth", + "thisYear", + "lastYear", + "today", + "beforeToday" ] }, "uniqueItems": true diff --git a/schemas/low-code/definitions/page-group-descriptor.schema.json b/schemas/low-code/definitions/page-group-descriptor.schema.json index c142f45500..f2fa4701cd 100644 --- a/schemas/low-code/definitions/page-group-descriptor.schema.json +++ b/schemas/low-code/definitions/page-group-descriptor.schema.json @@ -15,13 +15,19 @@ "description": "Unique URL-safe identifier for the group. Prefer kebab-case, for example 'crm' or 'content-studio'.", "minLength": 1 }, + "app": { + "type": "string", + "description": "Name of the low-code app that owns this group. Omit for the default app. Must match an apps[].name.", + "minLength": 1, + "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" + }, "title": { "type": "string", "description": "Display title for the menu group.", "minLength": 1 }, "icon": { - "type": "string", + "type": ["string", "null"], "description": "FontAwesome icon class, for example 'fa-solid fa-folder' or 'fa-solid fa-calendar-days'." }, "order": { @@ -30,12 +36,27 @@ "default": 0 }, "parent": { - "type": "string", - "description": "Name of the parent group for nesting. Must match another pageGroups[].name. Omit for root-level groups.", - "minLength": 1 + "type": ["string", "null"], + "description": "Name of the parent group for nesting. Must match another pageGroups[].name. Omit for root-level groups." + }, + "extendsLowerLayer": { + "type": "boolean", + "description": "When true, this descriptor overrides selected fields of a page group with the same name defined in a lower model layer; title becomes optional.", + "default": false + }, + "metadata": { + "$ref": "descriptor-metadata.schema.json" } }, - "required": ["name", "title"], + "required": ["name"], + "if": { + "properties": { "extendsLowerLayer": { "const": true } }, + "required": ["extendsLowerLayer"] + }, + "then": {}, + "else": { + "required": ["title"] + }, "additionalProperties": false, "examples": [ { "name": "events", "title": "Events", "icon": "fa-solid fa-calendar-days", "order": 10 }, diff --git a/schemas/low-code/definitions/page-relationship-descriptor.schema.json b/schemas/low-code/definitions/page-relationship-descriptor.schema.json new file mode 100644 index 0000000000..cbdf050f79 --- /dev/null +++ b/schemas/low-code/definitions/page-relationship-descriptor.schema.json @@ -0,0 +1,107 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "page-relationship-descriptor.schema.json", + "title": "PageRelationshipDescriptor", + "description": "Describes a reverse relationship shown on an entity page: records of a source entity whose foreign key points back to the host page record.", + "markdownDescription": "AI guidance: a foreign key on the source entity defines the schema direction; a page relationship defines how related records are shown from the host (target) page. `sourceEntityName`/`sourcePropertyName` identify the FK property that points at the page entity. Use `access: \"view\"` for read-only related lists and `access: \"edit\"` for CRUD. Use `generated` modes to let the runtime build the related page/forms from the source entity, `page`/`form` modes to reuse named descriptors, and `inherit` to reuse the related page's own create/edit forms. Set `useSeparatePermission: true` when child access must not inherit the host page permissions.", + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Stable identifier unique within the page, for example 'customer-orders'. Used by relationship permissions and runtime routes.", + "minLength": 1 + }, + "sourceEntityName": { + "type": "string", + "description": "Full name of the entity that owns the foreign key pointing at this page's entity.", + "minLength": 1 + }, + "sourcePropertyName": { + "type": "string", + "description": "Foreign key property on sourceEntityName that references the page entity.", + "minLength": 1 + }, + "access": { + "type": "string", + "description": "Access level from the host page: 'view' shows related records read-only; 'edit' allows create, update, and delete.", + "enum": ["view", "View", "edit", "Edit"], + "default": "view" + }, + "relatedPageMode": { + "type": "string", + "description": "How the related list is rendered. 'generated' builds a list from the source entity; 'page' reuses the page named by relatedPageName.", + "enum": ["generated", "Generated", "page", "Page"] + }, + "relatedPageName": { + "type": ["string", "null"], + "description": "Existing page name for the source entity. Required when relatedPageMode is 'page'." + }, + "createFormMode": { + "type": "string", + "description": "Form used to create related records. 'generated' builds a form from the source entity; 'inherit' reuses the related page's create form; 'form' uses createFormName.", + "enum": ["generated", "Generated", "inherit", "Inherit", "form", "Form"] + }, + "createFormName": { + "type": ["string", "null"], + "description": "Form descriptor name for the source entity. Required when createFormMode is 'form'." + }, + "editFormMode": { + "type": "string", + "description": "Form used to edit related records. 'generated' builds a form from the source entity; 'inherit' reuses the related page's edit form; 'form' uses editFormName.", + "enum": ["generated", "Generated", "inherit", "Inherit", "form", "Form"] + }, + "editFormName": { + "type": ["string", "null"], + "description": "Form descriptor name for the source entity. Required when editFormMode is 'form'." + }, + "useSeparatePermission": { + "type": "boolean", + "description": "When true, relationship view/create/update/delete permissions are resolved for the host page and relationship id instead of inheriting the host page decision.", + "default": false + }, + "permissionConfig": { + "$ref": "page-permission-config.schema.json", + "description": "Optional relationship permission overrides used when useSeparatePermission is true." + } + }, + "required": ["id", "sourceEntityName", "sourcePropertyName", "relatedPageMode", "createFormMode", "editFormMode"], + "allOf": [ + { + "if": { "properties": { "relatedPageMode": { "enum": ["page", "Page"] } }, "required": ["relatedPageMode"] }, + "then": { "required": ["relatedPageName"], "properties": { "relatedPageName": { "type": "string", "minLength": 1 } } } + }, + { + "if": { "properties": { "createFormMode": { "enum": ["form", "Form"] } }, "required": ["createFormMode"] }, + "then": { "required": ["createFormName"], "properties": { "createFormName": { "type": "string", "minLength": 1 } } } + }, + { + "if": { "properties": { "editFormMode": { "enum": ["form", "Form"] } }, "required": ["editFormMode"] }, + "then": { "required": ["editFormName"], "properties": { "editFormName": { "type": "string", "minLength": 1 } } } + } + ], + "additionalProperties": false, + "examples": [ + { + "id": "customer-orders", + "sourceEntityName": "Acme.Orders.Order", + "sourcePropertyName": "CustomerId", + "access": "edit", + "relatedPageMode": "page", + "relatedPageName": "orders", + "createFormMode": "generated", + "editFormMode": "generated" + }, + { + "id": "author-books", + "sourceEntityName": "Acme.Books.Book", + "sourcePropertyName": "AuthorId", + "access": "edit", + "relatedPageMode": "generated", + "createFormMode": "generated", + "editFormMode": "form", + "editFormName": "book-edit-for-author", + "useSeparatePermission": true, + "permissionConfig": { "view": "default", "create": "Acme.Books.Create" } + } + ] +} diff --git a/schemas/low-code/definitions/permission-descriptor.schema.json b/schemas/low-code/definitions/permission-descriptor.schema.json index 1abeb49841..0a2d69d031 100644 --- a/schemas/low-code/definitions/permission-descriptor.schema.json +++ b/schemas/low-code/definitions/permission-descriptor.schema.json @@ -3,7 +3,7 @@ "$id": "permission-descriptor.schema.json", "title": "PermissionDescriptor", "description": "Defines a custom permission created through the designer. Supports parent-child hierarchy.", - "markdownDescription": "AI guidance: use stable dot-separated permission names, for example `Acme.Events.Create`. Define a parent permission for the feature and child permissions for operations. Pages and endpoints can reference these names. Permission definitions only declare permissions; roles/users must still be granted permissions through permission management.", + "markdownDescription": "AI guidance: use stable dot-separated permission names, for example `Acme.Events.Create`. Define a parent permission for the feature and child permissions for operations. Pages and endpoints can reference these names. Permission definitions only declare permissions; roles/users must still be granted permissions through permission management. Children inherit the parent `app` unless they set their own.", "type": "object", "properties": { "$schema": { @@ -15,6 +15,12 @@ "description": "Unique dot-separated permission name, for example 'Acme.Events.Create'.", "minLength": 1 }, + "app": { + "type": "string", + "description": "Name of the low-code app that owns this permission. Omit for the default app. Must match an apps[].name. Child permissions inherit it when omitted.", + "minLength": 1, + "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" + }, "displayName": { "type": "string", "description": "Human-readable display name shown in permission management UI.", @@ -26,9 +32,25 @@ "items": { "$ref": "#" } + }, + "extendsLowerLayer": { + "type": "boolean", + "description": "When true, this descriptor overrides selected fields of a permission with the same name defined in a lower model layer; displayName becomes optional.", + "default": false + }, + "metadata": { + "$ref": "descriptor-metadata.schema.json" } }, - "required": ["name", "displayName"], + "required": ["name"], + "if": { + "properties": { "extendsLowerLayer": { "const": true } }, + "required": ["extendsLowerLayer"] + }, + "then": {}, + "else": { + "required": ["displayName"] + }, "additionalProperties": false, "examples": [ { diff --git a/schemas/low-code/definitions/presentation-icon-reference.schema.json b/schemas/low-code/definitions/presentation-icon-reference.schema.json new file mode 100644 index 0000000000..9ed8cfae84 --- /dev/null +++ b/schemas/low-code/definitions/presentation-icon-reference.schema.json @@ -0,0 +1,26 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "presentation-icon-reference.schema.json", + "title": "PresentationIconReference", + "description": "References an icon used by enum value and boolean value presentations.", + "markdownDescription": "AI guidance: prefer `kind: \"class\"` with a FontAwesome class list such as `fa-solid fa-check` for source-controlled descriptors. `blob` references an icon uploaded through the designer and is only valid in the runtime model layer. `dataUrl` embeds a base64 PNG/WebP image (`data:image/png;base64,...`). `path` references a root-relative application path such as `/images/icons/ok.svg`.", + "type": "object", + "properties": { + "kind": { + "type": "string", + "description": "Icon source kind. 'class' is a CSS class list; 'blob' is a designer-uploaded icon blob name (64 hex chars plus .png/.webp); 'dataUrl' is an inline base64 PNG/WebP data URL; 'path' is a root-relative application path.", + "enum": ["class", "Class", "blob", "Blob", "dataUrl", "DataUrl", "path", "Path"] + }, + "value": { + "type": "string", + "description": "Icon value matching kind: a CSS class list, blob name, data URL, or root-relative path.", + "minLength": 1 + } + }, + "required": ["kind", "value"], + "additionalProperties": false, + "examples": [ + { "kind": "class", "value": "fa-solid fa-check" }, + { "kind": "path", "value": "/images/icons/approved.svg" } + ] +} diff --git a/schemas/low-code/definitions/script-background-job-descriptor.schema.json b/schemas/low-code/definitions/script-background-job-descriptor.schema.json index 9a186ad083..c04523a981 100644 --- a/schemas/low-code/definitions/script-background-job-descriptor.schema.json +++ b/schemas/low-code/definitions/script-background-job-descriptor.schema.json @@ -15,6 +15,12 @@ "description": "Unique identifier for the background job. Scripts/enqueuers reference this name.", "minLength": 1 }, + "app": { + "type": "string", + "description": "Name of the low-code app that owns this job. Omit for the default app. Must match an apps[].name.", + "minLength": 1, + "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" + }, "javascript": { "type": "string", "description": "JavaScript code to execute when the job is enqueued/run. Use context payload/job arguments where available and keep retry-safe.", @@ -23,9 +29,25 @@ "description": { "type": "string", "description": "Optional description for designer documentation and model health context." + }, + "extendsLowerLayer": { + "type": "boolean", + "description": "When true, this descriptor overrides selected fields of a job with the same name defined in a lower model layer; javascript becomes optional.", + "default": false + }, + "metadata": { + "$ref": "descriptor-metadata.schema.json" } }, - "required": ["name", "javascript"], + "required": ["name"], + "if": { + "properties": { "extendsLowerLayer": { "const": true } }, + "required": ["extendsLowerLayer"] + }, + "then": {}, + "else": { + "required": ["javascript"] + }, "additionalProperties": false, "examples": [ { diff --git a/schemas/low-code/definitions/script-background-worker-descriptor.schema.json b/schemas/low-code/definitions/script-background-worker-descriptor.schema.json index 2c0ba07eb8..f010d0ce9a 100644 --- a/schemas/low-code/definitions/script-background-worker-descriptor.schema.json +++ b/schemas/low-code/definitions/script-background-worker-descriptor.schema.json @@ -15,8 +15,14 @@ "description": "Unique identifier for the background worker.", "minLength": 1 }, + "app": { + "type": "string", + "description": "Name of the low-code app that owns this worker. Omit for the default app. Must match an apps[].name.", + "minLength": 1, + "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" + }, "period": { - "type": "integer", + "type": ["integer", "null"], "description": "Execution period in milliseconds. Example: 300000 for every 5 minutes.", "minimum": 1 }, @@ -32,14 +38,48 @@ "description": { "type": "string", "description": "Optional description for designer documentation and model health context." + }, + "extendsLowerLayer": { + "type": "boolean", + "description": "When true, this descriptor overrides selected fields of a worker with the same name defined in a lower model layer; javascript and the schedule become optional.", + "default": false + }, + "metadata": { + "$ref": "descriptor-metadata.schema.json" } }, - "required": ["name", "javascript"], - "anyOf": [ - { - "required": ["period"], - "not": { + "required": ["name"], + "if": { + "properties": { "extendsLowerLayer": { "const": true } }, + "required": ["extendsLowerLayer"] + }, + "then": {}, + "else": { + "required": ["javascript"], + "anyOf": [ + { + "required": ["period"], + "properties": { + "period": { "type": "integer", "minimum": 1 } + }, + "not": { + "required": ["cronExpression"], + "properties": { + "cronExpression": { + "type": "string", + "minLength": 1 + } + } + } + }, + { "required": ["cronExpression"], + "not": { + "required": ["period"], + "properties": { + "period": { "type": "integer" } + } + }, "properties": { "cronExpression": { "type": "string", @@ -47,24 +87,19 @@ } } } - }, - { - "required": ["cronExpression"], - "not": { "required": ["period"] }, - "properties": { - "cronExpression": { - "type": "string", - "minLength": 1 - } - } - } - ], + ] + }, "additionalProperties": false, "examples": [ { "name": "CleanupExpiredEvents", "period": 3600000, "javascript": "context.log('Running expired event cleanup.');" + }, + { + "name": "NightlySummary", + "cronExpression": "0 2 * * *", + "javascript": "context.log('Building nightly summary.');" } ] } diff --git a/schemas/low-code/definitions/script-event-handler-descriptor.schema.json b/schemas/low-code/definitions/script-event-handler-descriptor.schema.json index da29d7fd4d..4f9fea8665 100644 --- a/schemas/low-code/definitions/script-event-handler-descriptor.schema.json +++ b/schemas/low-code/definitions/script-event-handler-descriptor.schema.json @@ -15,6 +15,12 @@ "description": "Unique identifier for the handler. Prefer a descriptive name such as 'NotifyWhenEventCompleted'.", "minLength": 1 }, + "app": { + "type": "string", + "description": "Name of the low-code app that owns this handler. Omit for the default app. Must match an apps[].name.", + "minLength": 1, + "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" + }, "eventName": { "type": "string", "description": "Distributed event name to subscribe to. Must exactly match the publisher's event name.", @@ -28,9 +34,25 @@ "description": { "type": "string", "description": "Optional description for designer documentation and model health context." + }, + "extendsLowerLayer": { + "type": "boolean", + "description": "When true, this descriptor overrides selected fields of a handler with the same name defined in a lower model layer; eventName and javascript become optional.", + "default": false + }, + "metadata": { + "$ref": "descriptor-metadata.schema.json" } }, - "required": ["name", "eventName", "javascript"], + "required": ["name"], + "if": { + "properties": { "extendsLowerLayer": { "const": true } }, + "required": ["extendsLowerLayer"] + }, + "then": {}, + "else": { + "required": ["eventName", "javascript"] + }, "additionalProperties": false, "examples": [ { diff --git a/schemas/low-code/manifest.json b/schemas/low-code/manifest.json index de39544885..722cf0561a 100644 --- a/schemas/low-code/manifest.json +++ b/schemas/low-code/manifest.json @@ -1,10 +1,11 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", "name": "ABP Low-Code Model Descriptor Schemas", - "version": "10.5", - "publicBaseUrl": "https://raw.githubusercontent.com/abpframework/abp/rel-10.5/schemas/low-code", + "version": "10.8", + "publicBaseUrl": "https://raw.githubusercontent.com/abpframework/abp/rel-10.8/schemas/low-code", "definitionsPath": "definitions", "descriptorSchemas": { + "apps": "definitions/app-descriptor.schema.json", "enums": "definitions/enum-descriptor.schema.json", "entities": "definitions/entity-descriptor.schema.json", "endpoints": "definitions/endpoint-descriptor.schema.json", From 5b00797b817bfa4cdf129740447e4b2209cb2ae6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?SAL=C4=B0H=20=C3=96ZKARA?= Date: Wed, 16 Sep 2026 11:22:01 +0300 Subject: [PATCH 2/2] Tighten low-code schema constraints from review - Backend filter conditions require an explicit operator, allow exactly one value source (none for isNull/isNotNull, static boolean for hasValue), and drop relative-date operators that the backend filter resolver rejects - Enum extensions may use an empty values array; new enums still need one - Clarify the optional default app descriptor and forbid archiving it - Describe useResourceAuthorization as the fallback when requiredPermissions is empty; clarify app-scoped descriptor folder layout in docs --- docs/en/low-code/model-json.md | 6 +- .../definitions/app-descriptor.schema.json | 11 ++- .../endpoint-descriptor.schema.json | 4 +- .../definitions/enum-descriptor.schema.json | 15 +++- ...page-backend-filter-expression.schema.json | 71 ++++++++++++++----- 5 files changed, 78 insertions(+), 29 deletions(-) diff --git a/docs/en/low-code/model-json.md b/docs/en/low-code/model-json.md index 46132e655a..6340195208 100644 --- a/docs/en/low-code/model-json.md +++ b/docs/en/low-code/model-json.md @@ -42,9 +42,9 @@ Layout conventions: * `entities/`, `enums/`, and `permissions/` usually follow namespace-like folders such as `entities/Acme/Catalog/Product.json`. * `pageGroups/` usually stays flat as `pageGroups/{groupName}.json`. -* `pages/` stays flat as `pages/{pageName}.json`, even when the page belongs to a page group or is a dashboard. +* `pages/` stays flat as `pages/{pageName}.json` for the default app, even when the page belongs to a page group or is a dashboard. * Dashboard pages live in `pages/`; there is no separate dashboard descriptor folder. -* `apps/` holds one file per non-default [app](#apps), for example `apps/crm.json`. Descriptors that belong to an app are written under an app subfolder of their category, for example `entities/crm/Acme/Crm/Contact.json` or `pages/crm/contacts.json`. +* `apps/` holds one file per [app](#apps), for example `apps/crm.json`. Descriptors that belong to a non-default app get one extra app-level folder directly under their category and then follow the same layout rules: `entities/crm/Acme/Crm/Contact.json`, `pages/crm/contacts.json`, `forms/crm/contact-form.json`. * The runtime scans the directory tree directly. Do not add a combined index file next to `model/`. ## Example Files and Validation @@ -527,7 +527,7 @@ Filters are page-owned. Use `control: "auto"` unless you need a specific control `hasValue` is a UI alias. At runtime, `Yes` maps to `IsNotNull`, `No` maps to `IsNull`, and `All` does not add a filter. Relative-date operators need no value; the server resolves the range at query time. -Use a page `backendFilter` when a condition must always be applied by the server. The root is a single condition or a group with `items`; inside a group the first item has no `logic` and every following item sets `logic` to `and` or `or`. Each condition names a `propertyName`, an explicit `operator`, and exactly one value source: a static `value`, a registered `valueProvider`, or a `javaScript` expression. Backend filters are combined with the filters above and are not removable client state. See [Data Modeling and Page Behavior](data-modeling.md#backend-filters). +Use a page `backendFilter` when a condition must always be applied by the server. The root is a single condition or a group with `items`; inside a group the first item has no `logic` and every following item sets `logic` to `and` or `or`. Each condition names a `propertyName`, an explicit `operator`, and exactly one value source: a static `value`, a registered `valueProvider`, or a `javaScript` expression. `isNull`/`isNotNull` take no value source and `hasValue` takes a static boolean `value`; `default` and the relative-date operators are not available in backend filters. Backend filters are combined with the filters above and are not removable client state. See [Data Modeling and Page Behavior](data-modeling.md#backend-filters). ## Permissions diff --git a/schemas/low-code/definitions/app-descriptor.schema.json b/schemas/low-code/definitions/app-descriptor.schema.json index 0a17f739a9..64a794aa4a 100644 --- a/schemas/low-code/definitions/app-descriptor.schema.json +++ b/schemas/low-code/definitions/app-descriptor.schema.json @@ -3,7 +3,7 @@ "$id": "app-descriptor.schema.json", "title": "AppDescriptor", "description": "Describes a low-code app. Apps partition the model into independently named scopes: other descriptors reference their owning app through the `app` field, and the default app is implicit.", - "markdownDescription": "AI guidance: create an app only when a group of entities, pages, forms, and scripts should be isolated under its own name. `name` is a lowercase kebab-case identifier such as `crm` or `field-service` and becomes part of runtime entity names (`:`), app-scoped endpoint routes, and split descriptor file paths (`entities//...`). The reserved name `default` is the implicit app; descriptors without an `app` field belong to it. Set `isArchived` to hide an app without deleting its descriptors.", + "markdownDescription": "AI guidance: create an app only when a group of entities, pages, forms, and scripts should be isolated under its own name. `name` is a lowercase kebab-case identifier such as `crm` or `field-service` and becomes part of runtime entity names (`:`), app-scoped endpoint routes, and split descriptor file paths (`entities//...`). The name `default` denotes the implicit default app that always exists; descriptors without an `app` field belong to it. A `default` app descriptor is optional and only customizes the default app's `displayName`, `description`, and `metadata`; it cannot be archived. Set `isArchived` on other apps to hide them without deleting their descriptors.", "type": "object", "properties": { "$schema": { @@ -12,7 +12,7 @@ }, "name": { "type": "string", - "description": "Stable lowercase kebab-case app name, for example 'crm' or 'field-service'. Maximum 64 characters. 'default' is the implicit default app.", + "description": "Stable lowercase kebab-case app name, for example 'crm' or 'field-service'. Maximum 64 characters. 'default' addresses the implicit default app, whose descriptor is optional and cannot be archived.", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" @@ -37,6 +37,13 @@ } }, "required": ["name", "displayName"], + "if": { + "properties": { "name": { "const": "default" } }, + "required": ["name"] + }, + "then": { + "properties": { "isArchived": { "const": false } } + }, "additionalProperties": false, "examples": [ { diff --git a/schemas/low-code/definitions/endpoint-descriptor.schema.json b/schemas/low-code/definitions/endpoint-descriptor.schema.json index d5f112252e..cffe24260b 100644 --- a/schemas/low-code/definitions/endpoint-descriptor.schema.json +++ b/schemas/low-code/definitions/endpoint-descriptor.schema.json @@ -3,7 +3,7 @@ "$id": "endpoint-descriptor.schema.json", "title": "Custom Endpoint Descriptor", "description": "Defines a custom HTTP endpoint that executes server-side JavaScript code.", - "markdownDescription": "AI guidance: use custom endpoints for model-owned actions and lightweight APIs. `name` must be unique within its app. `route` should start with `/api/` and must not conflict with another route/method. Use `{id}` style path parameters when needed. With `routeScope: \"app\"` the route is published beneath `/api/low-code/apps//endpoints` instead of verbatim. Scripts can access request data through the endpoint context and return HTTP results with helpers such as `context.ok(value)`, `context.created(value)`, and `context.noContent()` where available. Require authentication by default; add `requiredPermissions` for protected operations or set `useResourceAuthorization: true` to authorize per endpoint name through ABP resource permissions.", + "markdownDescription": "AI guidance: use custom endpoints for model-owned actions and lightweight APIs. `name` must be unique within its app. `route` should start with `/api/` and must not conflict with another route/method. Use `{id}` style path parameters when needed. With `routeScope: \"app\"` the route is published beneath `/api/low-code/apps//endpoints` instead of verbatim. Scripts can access request data through the endpoint context and return HTTP results with helpers such as `context.ok(value)`, `context.created(value)`, and `context.noContent()` where available. Require authentication by default. Authorization is resolved in order: `requiredPermissions` when non-empty, otherwise `useResourceAuthorization: true` (per-endpoint resource permission), otherwise `requireAuthentication`.", "type": "object", "properties": { "$schema": { @@ -51,7 +51,7 @@ }, "useResourceAuthorization": { "type": "boolean", - "description": "When true, access is granted per endpoint name through the generated ABP resource permission for this endpoint, in addition to requiredPermissions.", + "description": "When true and requiredPermissions is empty, access is granted per endpoint name through the generated ABP resource permission for this endpoint (with the global Low-Code endpoint permission as fallback). When requiredPermissions contains values, those permissions are checked instead.", "default": false }, "requiredPermissions": { diff --git a/schemas/low-code/definitions/enum-descriptor.schema.json b/schemas/low-code/definitions/enum-descriptor.schema.json index a5415640be..136e15a8d0 100644 --- a/schemas/low-code/definitions/enum-descriptor.schema.json +++ b/schemas/low-code/definitions/enum-descriptor.schema.json @@ -40,7 +40,7 @@ }, "values": { "type": "array", - "description": "Ordered list of integer-backed enum values. Values are stored as integers; names are used for display and model readability.", + "description": "Ordered list of integer-backed enum values. Values are stored as integers; names are used for display and model readability. The array is always required; it may be empty only when extendsLowerLayer is true and the descriptor changes just displayName/order/metadata.", "items": { "type": "object", "properties": { @@ -80,14 +80,23 @@ "name" ], "additionalProperties": false - }, - "minItems": 1 + } } }, "required": [ "name", "values" ], + "if": { + "properties": { "extendsLowerLayer": { "const": true } }, + "required": ["extendsLowerLayer"] + }, + "then": {}, + "else": { + "properties": { + "values": { "minItems": 1 } + } + }, "additionalProperties": false, "examples": [ { diff --git a/schemas/low-code/definitions/page-backend-filter-expression.schema.json b/schemas/low-code/definitions/page-backend-filter-expression.schema.json index 3aa1346f2c..abc7a4a145 100644 --- a/schemas/low-code/definitions/page-backend-filter-expression.schema.json +++ b/schemas/low-code/definitions/page-backend-filter-expression.schema.json @@ -3,7 +3,7 @@ "$id": "page-backend-filter-expression.schema.json", "title": "PageBackendFilterExpression", "description": "Server-enforced filter expression for an entity page. A single condition or a nested and/or group tree that is always applied by the backend and cannot be removed by the client.", - "markdownDescription": "AI guidance: use `backendFilter` for tenant, ownership, role, or workflow scoping that must not be user-editable. The root is either one condition or a group with `items`. Inside a group the first item has no `logic`; every following item must set `logic` to `and` or `or` to combine with the previous items. A condition names a `propertyName`, an explicit `operator` (never `default`), and exactly one value source: a static `value`, a `valueProvider` name registered in `AbpLowCodePageBackendFilterOptions` (for example `CurrentUserId`, `CurrentUserRoles`, `CurrentTenantId`), or a `javaScript` expression. `isNull`/`isNotNull` need no value; `hasValue` takes a boolean value; `between` takes two values; `in`/`notIn` take an array.", + "markdownDescription": "AI guidance: use `backendFilter` for tenant, ownership, role, or workflow scoping that must not be user-editable. The root is either one condition or a group with `items`. Inside a group the first item has no `logic`; every following item must set `logic` to `and` or `or` to combine with the previous items. A condition names a `propertyName`, an explicit `operator` (never `default`), and exactly one value source: a static `value`, a `valueProvider` name registered in `AbpLowCodePageBackendFilterOptions` (for example `CurrentUserId`, `CurrentUserRoles`, `CurrentTenantId`), or a `javaScript` expression. `isNull`/`isNotNull` take no value source; `hasValue` takes a static boolean `value` (true = isNotNull, false = isNull); `between` takes two values; `in`/`notIn` take an array. Relative-date operators (`thisMonth`, `today`, ...) and `default` are not supported by backend filters; they belong to visible page filters.", "$defs": { "logic": { "type": "string", @@ -12,7 +12,7 @@ }, "operator": { "type": "string", - "description": "Filter operator. Must be explicit; 'default' is not allowed for backend filters. 'equals' is accepted as an alias of 'equal'.", + "description": "Filter operator. Must be explicit; 'default' and relative-date operators are not allowed for backend filters. 'equals' is accepted as an alias of 'equal'. String properties support contains/notContains/startsWith/endsWith/equal/notEqual/in/notIn; numeric, money, and date/time properties support between/equal/notEqual/greaterThan/greaterThanOrEqual/lessThan/lessThanOrEqual/in/notIn; boolean, guid, and enum properties support equal/notEqual/in/notIn; isNull/isNotNull/hasValue apply to any property.", "enum": [ "equal", "equals", @@ -30,15 +30,7 @@ "isNotNull", "hasValue", "in", - "notIn", - "thisWeek", - "lastWeek", - "thisMonth", - "lastMonth", - "thisYear", - "lastYear", - "today", - "beforeToday" + "notIn" ] }, "conditionFields": { @@ -65,15 +57,56 @@ "minLength": 1 } }, - "required": ["propertyName"], + "required": ["propertyName", "operator"], "additionalProperties": false, - "not": { - "anyOf": [ - { "required": ["value", "valueProvider"] }, - { "required": ["value", "javaScript"] }, - { "required": ["valueProvider", "javaScript"] } - ] - } + "allOf": [ + { + "not": { + "anyOf": [ + { "required": ["value", "valueProvider"] }, + { "required": ["value", "javaScript"] }, + { "required": ["valueProvider", "javaScript"] } + ] + } + }, + { + "if": { + "properties": { "operator": { "enum": ["isNull", "isNotNull"] } } + }, + "then": { + "not": { + "anyOf": [ + { "required": ["value"] }, + { "required": ["valueProvider"] }, + { "required": ["javaScript"] } + ] + } + }, + "else": { + "anyOf": [ + { "required": ["value"] }, + { "required": ["valueProvider"] }, + { "required": ["javaScript"] } + ] + } + }, + { + "if": { + "properties": { "operator": { "const": "hasValue" } } + }, + "then": { + "required": ["value"], + "properties": { + "value": { + "anyOf": [ + { "type": "boolean" }, + { "type": "string", "enum": ["true", "false", "True", "False"] } + ] + } + } + } + } + ] }, "groupFields": { "type": "object",