data.appdata.structure.apply

Apply a validated VirtualDataStructure into appdata catalog metadata and serving-Postgres DDL

Apply a validated VirtualDataStructure into catalog metadata and serving DDL.

Overview

Property	Value
Workflow type	Atomic
Library	App-appdata
Version	1.0

Input Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	Authenticated organization UUID
identity_app_uuid	uuid	Yes	—	Identity app UUID owning the data
structure	dict	Yes	—	Serialized VirtualDataStructure declaration
apply_plan	dict	No	—	Precompiled appdata metadata apply plan
dry_run	boolean	No	—	Validate and plan without writing metadata. DEFAULTS TO TRUE: a call that omits this field only simulates and writes nothing. Pass false to apply, and check applied=true in the result.
request_id	string	No	—	Caller request id for audit correlation
actor	string	No	—	Workflow caller or agent identifier

Output Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	Organization UUID echoed from input
identity_app_uuid	uuid	Yes	—	Identity app UUID echoed from input
data_structure_name	string	Yes	—	Applied data structure name
database_count	integer	Yes	—	Number of logical databases planned/applied
table_count	integer	Yes	—	Number of logical tables planned/applied
field_count	integer	Yes	—	Number of logical fields planned/applied
policy_count	integer	Yes	—	Number of policies planned/applied
schema_version	integer	Yes	—	Resulting schema version
applied	boolean	Yes	—	False for dry-run plans
warnings	list	Yes	—	Non-blocking validation or migration warnings
plan_hash	string	Yes	—	Deterministic apply plan hash
plan	dict	Yes	—	Compiled appdata metadata apply plan
applied_at	string	No	—	ISO-8601 apply timestamp
serving_schema	string	No	—	Serving Postgres schema name (app_<identity_app_uuid hex>)
serving_sql	list	No	—	Serving DDL statements compiled for this apply (dry-run and live)
serving_statement_count	integer	No	—	Number of serving DDL statements
serving_applied	boolean	No	—	True when serving DDL was executed on the serving database
failure_reason	string	No	—	Engine-stamped failure reason
failed_at_state	string	No	—	State when the workflow failed
failed_step	string	No	—	Failed DAG step name
failed_layer	integer	No	—	Failed DAG layer index
error	string	No	—	Engine-stamped exception message
error_type	string	No	—	Engine-stamped exception class name

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	complete	Apply data structure
completed	No	Yes	Yes	—	Applied
failed	No	Yes	No	—	Apply failed

State Diagram

Transitions

From	Action	To	Description
pending	complete	completed	—
pending	fail	failed	—

Outcomes

Outcome	Type	Description	State Data Keys
applied	SUCCESS	Apply a validated VirtualDataStructure into appdata catalog metadata and serving-Postgres DDL	data_structure_name, schema_version
failed	FAILURE	Appdata workflow failed	failure_reason

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "data.appdata.structure.apply",
  "initial_data": {
    "organization_uuid": "value",
    "identity_app_uuid": "value",
    "structure": "value"
  }
}