Browse Source

Add Low-Code API resource descriptor schema

pull/26186/head
SALİH ÖZKARA 2 months ago
parent
commit
669c34500a
Failed to extract signature
  1. 669
      schemas/low-code/definitions/api-resource-descriptor.schema.json
  2. 1
      schemas/low-code/manifest.json

669
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
}
}
}

1
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"
}

Loading…
Cancel
Save