{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://appstruct.dev/schemas/appstruct-v1.schema.json",
"title": "AppStruct App Spec v1",
"description": "Configuration schema for AppStruct root and domain YAML documents. Cross-file and semantic constraints are enforced by appstruct check.",
"oneOf": [
{
"$ref": "#/$defs/root"
},
{
"$ref": "#/$defs/domain"
}
],
"$defs": {
"appName": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]*$"
},
"typeName": {
"type": "string",
"pattern": "^[A-Z][A-Za-z0-9]*$"
},
"fieldName": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$"
},
"roleName": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$"
},
"scalar": {
"type": [
"string",
"number",
"boolean"
]
},
"root": {
"type": "object",
"required": [
"version",
"app",
"database",
"includes"
],
"properties": {
"version": {
"const": 1
},
"app": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"$ref": "#/$defs/appName"
}
},
"additionalProperties": false
},
"database": {
"type": "object",
"required": [
"provider"
],
"properties": {
"provider": {
"const": "postgres"
},
"dev": {
"type": "object",
"properties": {
"mode": {
"enum": [
"managed",
"external"
]
},
"migration": {
"enum": [
"auto",
"prompt",
"never",
"unmanaged"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"preset": {
"$ref": "#/$defs/preset"
},
"server": {
"$ref": "#/$defs/server"
},
"modules": {
"$ref": "#/$defs/modules"
},
"module_manifests": {
"type": "array",
"items": {
"type": "string",
"pattern": "^modules/[^/].*"
},
"uniqueItems": true
},
"includes": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"uniqueItems": true
}
},
"additionalProperties": false
},
"preset": {
"type": "object",
"required": [
"name",
"version"
],
"properties": {
"name": {
"const": "appstruct/saas"
},
"version": {
"const": 1
}
},
"additionalProperties": false
},
"modules": {
"type": "object",
"properties": {
"auth": {
"$ref": "#/$defs/authModule"
},
"billing": {
"$ref": "#/$defs/billingModule"
},
"rbac": {
"$ref": "#/$defs/rbacModule"
},
"tenant": {
"$ref": "#/$defs/tenantModule"
},
"audit": {
"$ref": "#/$defs/auditModule"
},
"mail": {
"$ref": "#/$defs/mailModule"
},
"jobs": {
"$ref": "#/$defs/jobsModule"
},
"webhooks": {
"$ref": "#/$defs/webhooksModule"
},
"realtime": {
"$ref": "#/$defs/realtimeModule"
},
"file": {
"$ref": "#/$defs/fileModule"
},
"report": {
"$ref": "#/$defs/reportModule"
},
"activity": {
"$ref": "#/$defs/activityModule"
}
},
"additionalProperties": false
},
"authModule": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"user_entity": {
"$ref": "#/$defs/typeName"
},
"registration": {
"type": "boolean"
},
"password_reset": {
"type": "boolean"
},
"oauth": {
"type": "boolean"
},
"providers": {
"type": "array",
"items": {
"oneOf": [
{
"enum": [
"oidc",
"google",
"github"
]
},
{
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"enum": [
"oidc",
"google",
"github"
]
},
"type": {
"enum": [
"oidc",
"oauth"
]
},
"enabled": {
"type": "boolean"
},
"allow_signup": {
"type": "boolean"
},
"capabilities": {
"type": "object",
"properties": {
"login": {
"type": "boolean"
},
"signup": {
"type": "boolean"
},
"account_linking": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
},
"uniqueItems": true
}
},
"additionalProperties": false
},
"billingModule": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"provider": {
"enum": [
"stripe"
]
},
"capabilities": {
"type": "object",
"properties": {
"subscriptions": {
"type": "boolean"
},
"trials": {
"type": "boolean"
},
"customer_portal": {
"type": "boolean"
},
"metered_usage": {
"type": "boolean"
}
},
"additionalProperties": false
},
"plans": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"price_env"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[a-z_][a-z0-9_-]*$"
},
"price_env": {
"type": "string",
"pattern": "^[A-Z_][A-Z0-9_]*$"
},
"trial_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"entitlements": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z_][a-z0-9_-]*$"
},
"uniqueItems": true
}
},
"additionalProperties": false
},
"uniqueItems": true
}
},
"additionalProperties": false
},
"rbacModule": {
"type": "object",
"properties": {
"roles": {
"type": "array",
"items": {
"$ref": "#/$defs/roleName"
},
"uniqueItems": true
},
"default_role": {
"$ref": "#/$defs/roleName"
}
},
"additionalProperties": false
},
"tenantModule": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
}
},
"additionalProperties": false
},
"auditModule": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"reader_roles": {
"type": "array",
"items": {
"$ref": "#/$defs/roleName"
},
"uniqueItems": true
}
},
"additionalProperties": false
},
"mailModule": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"provider": {
"enum": [
"capture",
"smtp",
"resend"
]
},
"from": {
"type": "string",
"minLength": 1
},
"templates": {
"type": "object",
"propertyNames": {
"pattern": "^[a-z0-9_-]+$"
},
"additionalProperties": {
"$ref": "#/$defs/mailTemplate"
}
}
},
"additionalProperties": false
},
"mailTemplate": {
"type": "object",
"required": [
"subject",
"text"
],
"properties": {
"subject": {
"type": "string"
},
"text": {
"type": "string"
},
"html": {
"type": "string"
}
},
"additionalProperties": false
},
"jobsModule": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"poll_interval_ms": {
"type": "integer",
"minimum": 10,
"maximum": 60000
},
"lease_seconds": {
"type": "integer",
"minimum": 1,
"maximum": 3600
},
"queues": {
"type": "object",
"propertyNames": {
"pattern": "^[a-z0-9_-]+$"
},
"additionalProperties": {
"$ref": "#/$defs/jobQueue"
}
},
"schedules": {
"type": "object",
"propertyNames": {
"pattern": "^[a-z0-9_-]+$"
},
"additionalProperties": {
"$ref": "#/$defs/jobSchedule"
}
}
},
"additionalProperties": false
},
"jobQueue": {
"type": "object",
"properties": {
"max_attempts": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"backoff_seconds": {
"type": "integer",
"minimum": 1,
"maximum": 3600
}
},
"additionalProperties": false
},
"jobSchedule": {
"type": "object",
"required": [
"cron",
"queue",
"kind"
],
"properties": {
"cron": {
"type": "string",
"minLength": 1
},
"queue": {
"type": "string",
"pattern": "^[a-z0-9_-]+$"
},
"kind": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"payload": {
"type": "string"
}
},
"additionalProperties": false
},
"webhooksModule": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"poll_interval_ms": {
"type": "integer",
"minimum": 10,
"maximum": 60000
},
"connect_timeout_ms": {
"type": "integer",
"minimum": 100,
"maximum": 25000
},
"read_timeout_ms": {
"type": "integer",
"minimum": 100,
"maximum": 25000
},
"request_timeout_ms": {
"type": "integer",
"minimum": 100,
"maximum": 25000
},
"endpoints": {
"type": "object",
"propertyNames": {
"pattern": "^[a-z0-9_-]+$"
},
"additionalProperties": {
"$ref": "#/$defs/webhookEndpoint"
}
}
},
"additionalProperties": false
},
"webhookEndpoint": {
"type": "object",
"required": [
"url",
"secret_env",
"events"
],
"properties": {
"url": {
"type": "string",
"minLength": 1
},
"secret_env": {
"type": "string",
"pattern": "^[A-Z][A-Z0-9_]*$"
},
"events": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1
}
},
"max_attempts": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"backoff_seconds": {
"type": "integer",
"minimum": 1,
"maximum": 3600
}
},
"additionalProperties": false
},
"realtimeModule": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"heartbeat_seconds": {
"type": "integer",
"minimum": 5,
"maximum": 300
},
"presence_ttl_seconds": {
"type": "integer",
"minimum": 15,
"maximum": 900
}
},
"additionalProperties": false
},
"fileModule": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"provider": {
"enum": [
"local",
"s3"
]
},
"local_root": {
"type": "string",
"minLength": 1
},
"max_bytes": {
"type": "integer",
"minimum": 1,
"maximum": 104857600
},
"allowed_content_types": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z0-9!#$&^_.+-]+/(\\*|[a-z0-9!#$&^_.+-]+)$"
},
"uniqueItems": true
}
},
"additionalProperties": false
},
"reportModule": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"renderer": {
"enum": [
"capture",
"chromium"
],
"default": "capture"
},
"queue": {
"type": "string",
"pattern": "^[a-z0-9_-]+$"
},
"max_input_bytes": {
"type": "integer",
"minimum": 1,
"maximum": 4194304
},
"retention_days": {
"type": "integer",
"minimum": 1,
"maximum": 3650
},
"reader_roles": {
"type": "array",
"items": {
"$ref": "#/$defs/roleName"
},
"uniqueItems": true
},
"templates": {
"type": "object",
"minProperties": 1,
"propertyNames": {
"pattern": "^[a-z0-9_-]{1,80}$"
},
"additionalProperties": {
"$ref": "#/$defs/reportTemplate"
}
}
},
"additionalProperties": false
},
"reportTemplate": {
"type": "object",
"required": [
"version",
"body",
"input_schema"
],
"properties": {
"version": {
"type": "integer",
"minimum": 1,
"maximum": 4294967295
},
"body": {
"type": "string",
"minLength": 1,
"maxLength": 1048576
},
"input_schema": {
"type": "string",
"minLength": 2
},
"data_schema_version": {
"type": "integer",
"minimum": 1,
"maximum": 4294967295
}
},
"additionalProperties": false
},
"activityModule": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"max_comment_bytes": {
"type": "integer",
"minimum": 1,
"maximum": 65536
},
"attachments": {
"type": "boolean"
},
"admin_roles": {
"type": "array",
"items": {
"$ref": "#/$defs/roleName"
},
"uniqueItems": true
},
"resources": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/$defs/typeName"
},
"uniqueItems": true
}
},
"additionalProperties": false
},
"domain": {
"type": "object",
"required": [
"domain"
],
"properties": {
"domain": {
"type": "string",
"minLength": 1
},
"entities": {
"type": "object",
"propertyNames": {
"$ref": "#/$defs/typeName"
},
"additionalProperties": {
"$ref": "#/$defs/entity"
}
},
"value_objects": {
"type": "object",
"propertyNames": {
"$ref": "#/$defs/typeName"
},
"additionalProperties": {
"$ref": "#/$defs/valueObject"
}
},
"commands": {
"type": "object",
"propertyNames": {
"$ref": "#/$defs/typeName"
},
"additionalProperties": {
"$ref": "#/$defs/command"
}
},
"queries": {
"type": "object",
"propertyNames": {
"$ref": "#/$defs/typeName"
},
"additionalProperties": {
"$ref": "#/$defs/query"
}
},
"pages": {
"type": "object",
"propertyNames": {
"$ref": "#/$defs/typeName"
},
"additionalProperties": {
"$ref": "#/$defs/page"
}
}
},
"additionalProperties": false
},
"entity": {
"type": "object",
"required": [
"fields"
],
"properties": {
"label": {
"type": "string"
},
"table": {
"$ref": "#/$defs/fieldName"
},
"fields": {
"type": "object",
"minProperties": 1,
"propertyNames": {
"$ref": "#/$defs/fieldName"
},
"additionalProperties": {
"$ref": "#/$defs/field"
}
},
"indexes": {
"type": "array",
"items": {
"$ref": "#/$defs/index"
}
},
"seeds": {
"type": "object",
"propertyNames": {
"$ref": "#/$defs/fieldName"
},
"additionalProperties": {
"$ref": "#/$defs/seed"
}
},
"access": {
"$ref": "#/$defs/crudAccess"
},
"tenant": {
"type": "boolean"
},
"audit": {
"type": "boolean"
},
"soft_delete": {
"type": "boolean"
},
"display_field": {
"type": "string",
"pattern": "^[A-Za-z][A-Za-z0-9_]*$"
},
"aggregates": {
"type": "object",
"propertyNames": {
"$ref": "#/$defs/fieldName"
},
"additionalProperties": {
"$ref": "#/$defs/aggregate"
}
},
"charts": {
"type": "object",
"maxProperties": 20,
"propertyNames": {
"$ref": "#/$defs/fieldName"
},
"additionalProperties": {
"$ref": "#/$defs/chart"
}
},
"workflow": {
"$ref": "#/$defs/workflow"
}
},
"additionalProperties": false
},
"aggregate": {
"type": "object",
"required": [
"entity",
"relation"
],
"properties": {
"entity": {
"$ref": "#/$defs/typeName"
},
"relation": {
"$ref": "#/$defs/fieldName"
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true
},
"max_items": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 100
}
},
"additionalProperties": false
},
"chart": {
"type": "object",
"required": [
"type",
"measure"
],
"properties": {
"label": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"type": {
"enum": [
"kpi",
"bar",
"horizontal_bar",
"donut"
]
},
"dimension": {
"type": "string",
"pattern": "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z][A-Za-z0-9_]*)?$"
},
"measure": {
"type": "string",
"pattern": "^(count|(sum|avg|min|max):[A-Za-z][A-Za-z0-9_]*)$"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
}
},
"additionalProperties": false
},
"workflow": {
"type": "object",
"required": [
"field",
"initial",
"transitions"
],
"properties": {
"field": {
"$ref": "#/$defs/fieldName"
},
"initial": {
"type": "string",
"minLength": 1
},
"transitions": {
"type": "object",
"minProperties": 1,
"propertyNames": {
"$ref": "#/$defs/fieldName"
},
"additionalProperties": {
"$ref": "#/$defs/workflowTransition"
}
}
},
"additionalProperties": false
},
"workflowTransition": {
"type": "object",
"required": [
"from",
"to",
"access"
],
"properties": {
"from": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"minLength": 1
},
"uniqueItems": true
},
"to": {
"type": "string",
"minLength": 1
},
"input": {
"$ref": "#/$defs/typeName"
},
"access": {
"$ref": "#/$defs/accessRule"
}
},
"additionalProperties": false
},
"index": {
"type": "object",
"required": [
"fields"
],
"properties": {
"name": {
"$ref": "#/$defs/fieldName"
},
"fields": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/$defs/fieldName"
},
"uniqueItems": true
},
"unique": {
"type": "boolean"
},
"where": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
},
"seed": {
"type": "object",
"minProperties": 1,
"additionalProperties": {
"$ref": "#/$defs/scalar"
}
},
"field": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"enum": [
"uuid",
"string",
"text",
"integer",
"bigint",
"decimal",
"boolean",
"date",
"datetime",
"json",
"enum",
"relation"
]
},
"column": {
"$ref": "#/$defs/fieldName"
},
"primary_key": {
"type": "boolean"
},
"required": {
"type": "boolean"
},
"unique": {
"type": "boolean"
},
"generated": {
"enum": [
"uuid_v7",
"now",
"auto_increment"
]
},
"default": {
"$ref": "#/$defs/scalar"
},
"min_length": {
"type": "integer",
"minimum": 0
},
"max_length": {
"type": "integer",
"minimum": 0
},
"minimum": {
"type": [
"string",
"number"
]
},
"maximum": {
"type": [
"string",
"number"
]
},
"searchable": {
"type": "boolean"
},
"filterable": {
"type": "boolean"
},
"sortable": {
"type": "boolean"
},
"access": {
"$ref": "#/$defs/fieldAccess"
},
"values": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"minLength": 1
},
"uniqueItems": true
},
"target": {
"type": "string",
"pattern": "^(app::)?[A-Z][A-Za-z0-9]*$"
},
"on_delete": {
"enum": [
"restrict",
"cascade",
"set_null"
]
},
"ui": {
"type": "object",
"properties": {
"component": {
"$ref": "#/$defs/typeName"
},
"semantic": {
"const": "money"
},
"currency_field": {
"$ref": "#/$defs/fieldName"
},
"fraction_digits": {
"type": "integer",
"minimum": 0,
"maximum": 6,
"default": 2
}
},
"additionalProperties": false,
"oneOf": [
{
"required": [
"component"
],
"not": {
"anyOf": [
{
"required": [
"semantic"
]
},
{
"required": [
"currency_field"
]
},
{
"required": [
"fraction_digits"
]
}
]
}
},
{
"required": [
"semantic",
"currency_field"
],
"not": {
"required": [
"component"
]
}
}
]
},
"required_when": {
"type": "object",
"required": [
"field",
"equals"
],
"properties": {
"field": {
"$ref": "#/$defs/fieldName"
},
"equals": {
"type": [
"string",
"boolean"
]
}
},
"additionalProperties": false
},
"greater_than": {
"$ref": "#/$defs/fieldName"
}
},
"additionalProperties": false
},
"crudAccess": {
"type": "object",
"properties": {
"list": {
"$ref": "#/$defs/accessRule"
},
"read": {
"$ref": "#/$defs/accessRule"
},
"create": {
"$ref": "#/$defs/accessRule"
},
"update": {
"$ref": "#/$defs/accessRule"
},
"delete": {
"$ref": "#/$defs/accessRule"
}
},
"additionalProperties": false
},
"fieldAccess": {
"type": "object",
"properties": {
"read": {
"$ref": "#/$defs/accessRule"
},
"write": {
"$ref": "#/$defs/accessRule"
}
},
"additionalProperties": false
},
"accessRule": {
"oneOf": [
{
"type": "object",
"required": [
"public"
],
"properties": {
"public": {
"const": true
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"authenticated"
],
"properties": {
"authenticated": {
"const": true
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"role"
],
"properties": {
"role": {
"$ref": "#/$defs/roleName"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"owner"
],
"properties": {
"owner": {
"$ref": "#/$defs/fieldName"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"any"
],
"properties": {
"any": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/$defs/accessRule"
}
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"all"
],
"properties": {
"all": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/$defs/accessRule"
}
}
},
"additionalProperties": false
}
]
},
"valueObject": {
"type": "object",
"required": [
"fields"
],
"properties": {
"fields": {
"type": "object",
"minProperties": 1,
"propertyNames": {
"$ref": "#/$defs/fieldName"
},
"additionalProperties": {
"$ref": "#/$defs/valueField"
}
}
},
"additionalProperties": false
},
"valueField": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"enum": [
"uuid",
"string",
"text",
"integer",
"bigint",
"decimal",
"boolean",
"date",
"datetime",
"json",
"enum"
]
},
"required": {
"type": "boolean"
},
"values": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"minLength": 1
},
"uniqueItems": true
}
},
"additionalProperties": false
},
"operationBase": {
"type": "object",
"required": [
"output",
"access"
],
"properties": {
"input": {
"$ref": "#/$defs/typeName"
},
"output": {
"$ref": "#/$defs/typeName"
},
"access": {
"$ref": "#/$defs/accessRule"
}
},
"additionalProperties": false
},
"command": {
"allOf": [
{
"$ref": "#/$defs/operationBase"
},
{
"required": [
"input"
]
}
]
},
"query": {
"$ref": "#/$defs/operationBase"
},
"page": {
"type": "object",
"required": [
"path",
"component"
],
"properties": {
"label": {
"type": "string"
},
"path": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]*(/[a-z][a-z0-9-]*)*$"
},
"component": {
"$ref": "#/$defs/typeName"
}
},
"additionalProperties": false
},
"server": {
"type": "object",
"properties": {
"security_headers": {
"$ref": "#/$defs/securityHeaders"
}
},
"additionalProperties": false
},
"securityHeaders": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Emit security response headers. Defaults to true."
},
"hsts": {
"description": "`auto` emits Strict-Transport-Security only in production, `off` disables it, or an integer sets max-age seconds.",
"oneOf": [
{
"type": "string",
"enum": [
"auto",
"off"
]
},
{
"type": "integer",
"minimum": 0
}
]
},
"frame_options": {
"type": "string",
"enum": [
"deny",
"sameorigin",
"off"
]
},
"referrer_policy": {
"type": "string",
"enum": [
"no-referrer",
"same-origin",
"strict-origin-when-cross-origin",
"off"
]
},
"content_security_policy": {
"type": [
"string",
"null"
]
},
"custom": {
"type": "object",
"propertyNames": {
"pattern": "^[a-z0-9-]+$"
},
"additionalProperties": {
"type": "string"
}
}
},
"additionalProperties": false
}
}
}