diff --git a/schemas/low-code/definitions/api-resource-descriptor.schema.json b/schemas/low-code/definitions/api-resource-descriptor.schema.json new file mode 100644 index 0000000000..c226f3874c --- /dev/null +++ b/schemas/low-code/definitions/api-resource-descriptor.schema.json @@ -0,0 +1,669 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "api-resource-descriptor.schema.json", + "title": "ApiResourceDescriptor", + "description": "Describes a named, reusable entity API exposed without a page. One entity may have multiple API resources; each defines its own operations, field policies, filters, permissions, and interceptors.", + "markdownDescription": "AI guidance: `name` is the stable API route key and should be URL-safe kebab-case (for example `orders-api`). `entityName` must reference an existing entity. API resources expose REST endpoints at `api/low-code/api-resources/{name}` (or `api/low-code/apps/{app}/api-resources/{name}`). Use `operations` to disable individual operations, `responseFields` to project returned properties per operation, `writableFields` to allowlist submitted properties per write operation, `backendFilter` to scope Query and Export, `inputFilter` to reject write payloads that violate conditions, and `interceptors` for JavaScript hooks on command (Create, Update, Replace, Delete) and query (Query, Get) pipelines.", + "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 URL-safe API resource identifier. Prefer kebab-case, for example 'orders-api' or 'customer-lookup'. This becomes part of the runtime route.", + "minLength": 1 + }, + "app": { + "type": "string", + "description": "Name of the app this API resource belongs to. Omit for the default app.", + "minLength": 1 + }, + "entityName": { + "type": "string", + "description": "Full name of the entity this API resource exposes. Required unless extendsLowerLayer is set.", + "minLength": 1 + }, + "description": { + "type": "string", + "description": "Optional human-readable description of the API resource." + }, + "extendsLowerLayer": { + "type": "boolean", + "description": "When true, this descriptor extends an API resource with the same name defined in a lower model layer instead of replacing it." + }, + "operations": { + "type": "object", + "description": "Per-operation enablement switches. Omitted operations stay enabled; 'replace' falls back to 'update' when not authored.", + "properties": { + "get": { + "type": "boolean", + "description": "Enable the single-record endpoint." + }, + "create": { + "type": "boolean", + "description": "Enable record creation." + }, + "update": { + "type": "boolean", + "description": "Enable record updates." + }, + "replace": { + "type": "boolean", + "description": "Enable full replacement (PUT). Falls back to the 'update' flag when omitted." + }, + "delete": { + "type": "boolean", + "description": "Enable record deletion." + }, + "lookup": { + "type": "boolean", + "description": "Enable lookup endpoints used by foreign-key selectors." + }, + "export": { + "type": "boolean", + "description": "Enable export endpoints." + }, + "import": { + "type": "boolean", + "description": "Enable import endpoints." + }, + "files": { + "type": "boolean", + "description": "Enable file upload/download endpoints." + }, + "attachments": { + "type": "boolean", + "description": "Enable attachment endpoints." + }, + "query": { + "type": "boolean", + "description": "Enable the Query endpoint." + } + }, + "additionalProperties": false + }, + "responseFields": { + "type": "object", + "description": "Per-operation response projection (entity property names). Only the listed properties are returned for that operation; omitted operations return all properties.", + "properties": { + "get": { + "$ref": "#/$defs/propertyNameList", + "description": "Properties returned by the single-record endpoint." + }, + "create": { + "$ref": "#/$defs/propertyNameList", + "description": "Properties returned after create." + }, + "update": { + "$ref": "#/$defs/propertyNameList", + "description": "Properties returned after update." + }, + "replace": { + "$ref": "#/$defs/propertyNameList", + "description": "Properties returned after replace." + }, + "query": { + "$ref": "#/$defs/propertyNameList", + "description": "Properties returned by the list endpoint." + } + }, + "additionalProperties": false + }, + "writableFields": { + "type": "object", + "description": "Per-operation input allowlist (entity property names). Submitted properties outside the list are rejected for that operation; omitted operations accept all writable properties. 'replace' falls back to 'update' when not authored.", + "properties": { + "create": { + "$ref": "#/$defs/propertyNameList", + "description": "Properties accepted on create." + }, + "update": { + "$ref": "#/$defs/propertyNameList", + "description": "Properties accepted on update." + }, + "replace": { + "$ref": "#/$defs/propertyNameList", + "description": "Properties accepted on replace." + } + }, + "additionalProperties": false + }, + "defaultSortProperty": { + "type": "string", + "description": "Property name used for default sorting. Must reference a sortable scalar property on entityName.", + "minLength": 1 + }, + "defaultSortDescending": { + "type": "boolean", + "description": "Whether the default sort is descending." + }, + "backendFilter": { + "$ref": "#/$defs/filterExpression", + "description": "Backend filter applied to read queries and to update/delete/file scoping." + }, + "inputFilter": { + "$ref": "#/$defs/filterExpression", + "description": "Conditions the submitted input must satisfy for create/update/replace; violating payloads are rejected." + }, + "permissionConfig": { + "$ref": "page-permission-config.schema.json", + "description": "Per-operation permission configuration. Omitted operations use auto-generated defaults based on the API resource." + }, + "interceptors": { + "type": "array", + "description": "JavaScript interceptors for api-resource commands and queries. At most one interceptor per (commandName, type).", + "items": { + "type": "object", + "properties": { + "commandName": { + "type": "string", + "description": "Operation to intercept: Create, Update, Replace, or Delete run on the command pipeline; Query and Get run on the query pipeline.", + "enum": [ + "Create", + "Update", + "Replace", + "Delete", + "Query", + "Get", + "Export", + "Import", + "Files", + "Attachments" + ] + }, + "type": { + "$ref": "interceptor-type.schema.json", + "description": "Whether the script runs before or after the operation." + }, + "javascript": { + "type": "string", + "description": "JavaScript code to execute. For Pre command interceptors, set globalError to block the operation." + }, + "entityExecutionOrder": { + "type": "string", + "enum": [ + "entityFirst", + "pageFirst", + "skipEntity", + "apiResourceFirst" + ], + "description": "How this interceptor orders relative to entity interceptors on the command pipeline. Only meaningful for command commands." + } + }, + "required": [ + "commandName", + "type", + "javascript" + ], + "additionalProperties": false + } + }, + "metadata": { + "type": "object", + "description": "Arbitrary key/value metadata carried with the descriptor.", + "additionalProperties": { + "type": [ + "string", + "null" + ] + } + }, + "resultType": { + "type": "string", + "description": "Query result shape. Custom executes queryJavascript and returns its projected, bounded list.", + "enum": [ + "paged", + "list", + "aggregate", + "groupedAggregate", + "groupedRecords", + "custom" + ], + "default": "paged" + }, + "groupByProperty": { + "type": "string", + "description": "Group by property" + }, + "aggregationType": { + "type": "string", + "description": "Aggregation", + "enum": [ + "count", + "sum", + "average", + "min", + "max", + "percentFilled", + "percentEmpty" + ], + "default": "count" + }, + "aggregationProperty": { + "type": "string", + "description": "Aggregate property" + }, + "dateGrouping": { + "type": "string", + "description": "Date grouping", + "enum": [ + "year", + "quarter", + "month", + "week", + "day" + ] + }, + "inputValidation": { + "type": "object", + "description": "Per-operation constraints on the resulting record, in addition to shared inputFilter and entity validation.", + "properties": { + "create": { + "$ref": "#/$defs/filterExpression" + }, + "update": { + "$ref": "#/$defs/filterExpression" + }, + "replace": { + "$ref": "#/$defs/filterExpression" + } + }, + "additionalProperties": false + }, + "recordScopes": { + "type": "object", + "description": "Independent operation scopes. Identity is always read from the server session. Missing scope means all records permitted by the resource and tenant.", + "additionalProperties": false, + "properties": { + "query": { + "type": "object", + "properties": { + "kind": { + "enum": [ + "all", + "createdByCurrentUser", + "assignedToCurrentUser" + ] + }, + "userProperty": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "kind" + ], + "additionalProperties": false + }, + "get": { + "type": "object", + "properties": { + "kind": { + "enum": [ + "all", + "createdByCurrentUser", + "assignedToCurrentUser" + ] + }, + "userProperty": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "kind" + ], + "additionalProperties": false + }, + "update": { + "type": "object", + "properties": { + "kind": { + "enum": [ + "all", + "createdByCurrentUser", + "assignedToCurrentUser" + ] + }, + "userProperty": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "kind" + ], + "additionalProperties": false + }, + "replace": { + "type": "object", + "properties": { + "kind": { + "enum": [ + "all", + "createdByCurrentUser", + "assignedToCurrentUser" + ] + }, + "userProperty": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "kind" + ], + "additionalProperties": false + }, + "delete": { + "type": "object", + "properties": { + "kind": { + "enum": [ + "all", + "createdByCurrentUser", + "assignedToCurrentUser" + ] + }, + "userProperty": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "kind" + ], + "additionalProperties": false + }, + "lookup": { + "type": "object", + "properties": { + "kind": { + "enum": [ + "all", + "createdByCurrentUser", + "assignedToCurrentUser" + ] + }, + "userProperty": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "kind" + ], + "additionalProperties": false + }, + "export": { + "type": "object", + "properties": { + "kind": { + "enum": [ + "all", + "createdByCurrentUser", + "assignedToCurrentUser" + ] + }, + "userProperty": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "kind" + ], + "additionalProperties": false + }, + "import": { + "type": "object", + "properties": { + "kind": { + "enum": [ + "all", + "createdByCurrentUser", + "assignedToCurrentUser" + ] + }, + "userProperty": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "kind" + ], + "additionalProperties": false + }, + "files": { + "type": "object", + "properties": { + "kind": { + "enum": [ + "all", + "createdByCurrentUser", + "assignedToCurrentUser" + ] + }, + "userProperty": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "kind" + ], + "additionalProperties": false + }, + "attachments": { + "type": "object", + "properties": { + "kind": { + "enum": [ + "all", + "createdByCurrentUser", + "assignedToCurrentUser" + ] + }, + "userProperty": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "kind" + ], + "additionalProperties": false + } + } + }, + "getResultType": { + "type": "string", + "enum": [ + "record", + "custom" + ], + "default": "record" + }, + "queryJavascript": { + "type": [ + "string", + "null" + ], + "description": "Custom result JavaScript. Return the supplied filtered query after projection; do not materialize it. Query returns a bounded list and Get returns a single object." + }, + "getJavascript": { + "type": [ + "string", + "null" + ], + "description": "Custom result JavaScript. Return the supplied filtered query after projection; do not materialize it. Query returns a bounded list and Get returns a single object." + }, + "exportFields": { + "type": [ + "array", + "null" + ], + "items": { + "type": "object", + "properties": { + "propertyName": { + "type": "string" + }, + "label": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "propertyName" + ], + "additionalProperties": false + }, + "description": "Allowed export columns in output order, with optional header labels. Null uses Query response fields." + }, + "importFields": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + }, + "uniqueItems": true + }, + "fileFields": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + }, + "uniqueItems": true + }, + "importModes": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string", + "enum": [ + "append", + "merge" + ] + }, + "uniqueItems": true + }, + "fileActions": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string", + "enum": [ + "upload", + "download" + ] + }, + "uniqueItems": true + }, + "attachmentActions": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string", + "enum": [ + "list", + "upload", + "download", + "delete" + ] + }, + "uniqueItems": true + }, + "allowFileBundleExport": { + "type": [ + "boolean", + "null" + ] + } + }, + "required": [ + "name", + "entityName" + ], + "additionalProperties": false, + "$defs": { + "propertyNameList": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + } + }, + "filterExpression": { + "description": "A single condition object or a group with an 'items' array. Non-first items inside a group must declare 'logic' ('and' or 'or'). A condition carries 'propertyName', optional 'operator', and exactly one value source: 'value', 'valueProvider', or 'javaScript'.", + "type": "object", + "properties": { + "logic": { + "type": "string", + "enum": [ + "and", + "or" + ] + }, + "propertyName": { + "type": "string", + "minLength": 1 + }, + "operator": { + "type": "string" + }, + "value": {}, + "valueProvider": { + "type": "string" + }, + "javaScript": { + "type": "string" + }, + "items": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/filterExpression" + } + } + }, + "additionalProperties": false + } + } +} diff --git a/schemas/low-code/manifest.json b/schemas/low-code/manifest.json index 722cf0561a..c5e7e4a334 100644 --- a/schemas/low-code/manifest.json +++ b/schemas/low-code/manifest.json @@ -14,6 +14,7 @@ "backgroundWorkers": "definitions/script-background-worker-descriptor.schema.json", "pageGroups": "definitions/page-group-descriptor.schema.json", "pages": "definitions/page-descriptor.schema.json", + "apiResources": "definitions/api-resource-descriptor.schema.json", "forms": "definitions/form-descriptor.schema.json", "permissions": "definitions/permission-descriptor.schema.json" }