{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://scrollcase.dev/schema/v2/execution.schema.json",
"title": "Box execution",
"description": "The optional, shell-free application entry point shared by a scroll, the signed release, and box.json. Its absence means the box is intentionally library-only.",
"oneOf": [
{
"title": "Python script",
"description": "Run one regular payload file with the box's own Python interpreter.",
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"script",
"defaultArgs"
],
"properties": {
"kind": {
"const": "python-script",
"description": "Selects direct script execution."
},
"script": {
"$ref": "#/$defs/payloadPath",
"description": "Safe path to a regular Python file inside the box."
},
"defaultArgs": {
"$ref": "#/$defs/defaultArgs"
}
}
},
{
"title": "Python module",
"description": "Run an importable dotted module with Python's -m option.",
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"module",
"defaultArgs"
],
"properties": {
"kind": {
"const": "python-module",
"description": "Selects dotted-module execution."
},
"module": {
"type": "string",
"pattern": "^[A-Za-z_][A-Za-z0-9_]*(?:\\.[A-Za-z_][A-Za-z0-9_]*)*$",
"description": "Strict Python dotted-module name, without command-line syntax or shell fragments.",
"examples": [
"example_model.main"
]
},
"defaultArgs": {
"$ref": "#/$defs/defaultArgs"
}
}
}
],
"examples": [
{
"kind": "python-script",
"script": "entrypoint.py",
"defaultArgs": []
},
{
"kind": "python-module",
"module": "example_model.main",
"defaultArgs": [
"--serve"
]
}
],
"$defs": {
"defaultArgs": {
"type": "array",
"description": "Arguments placed before caller-supplied arguments. Every item is passed directly without a shell.",
"default": [],
"items": {
"type": "string"
}
},
"payloadPath": {
"type": "string",
"minLength": 1,
"pattern": "^(?!/)(?![A-Za-z]:)(?!.*\\\\)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*//).+$",
"description": "A forward-slash path inside the box payload: relative, non-empty, and unable to escape the payload root.",
"examples": [
"entrypoint.py",
"app/main.py"
]
}
}
}