{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "script-background-worker-descriptor.schema.json", "title": "Script Background Worker Descriptor", "description": "Defines a scheduled JavaScript background worker.", "markdownDescription": "AI guidance: use background workers for recurring scheduled work. Provide either `period` in milliseconds or `cronExpression`; do not provide both unless the host explicitly chooses one. Keep scripts idempotent and short. Use workers for polling, cleanup, synchronization, or recurring summary generation.", "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": "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", "null"], "description": "Execution period in milliseconds. Example: 300000 for every 5 minutes.", "minimum": 1 }, "cronExpression": { "type": ["string", "null"], "description": "Cron expression for scheduler-backed providers. Omit it, set it to null, or leave it empty when the worker uses period-based scheduling." }, "javascript": { "type": "string", "description": "JavaScript code to execute when the worker runs. Keep idempotent; workers may overlap or retry depending on scheduler configuration.", "minLength": 1 }, "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"], "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", "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.');" } ] }