[WIP] workflow builder

work-summary/2026-02-unified-schema-format.md

@@ -0,0 +1,88 @@
+# Unified Schema Format: Flat Format for All Schema Types
+
+**Date**: 2026-02-05
+
+## Summary
+
+Unified all schema types (`param_schema`, `out_schema`, `conf_schema`) to use the same flat StackStorm-style format with inline `required` and `secret` per parameter. Previously, `param_schema` used flat format while `out_schema` and `conf_schema` used standard JSON Schema (`{ type: "object", properties: { ... }, required: [...] }`). This inconsistency prevented features like `secret` badges from working on output and configuration schemas.
+
+## Motivation
+
+- No reason for `conf_schema` and `out_schema` to use a different format than `param_schema`
+- Users should be able to mark `secret` and `required` inline on any schema type
+- Eliminates dual-format shim logic in the web UI (`extractProperties` backward compatibility branch)
+- Project is pre-production — no data migration needed, just adjust configurations
+
+## Changes
+
+### Pack YAML Files (12 files)
+
+Converted all top-level `type: object` + `properties` wrappers to flat format, moving `required` array entries inline:
+
+- `packs/core/pack.yaml` — `conf_schema`
+- `packs/examples/pack.yaml` — `conf_schema`
+- `packs/core/sensors/interval_timer_sensor.yaml` — `parameters`
+- `packs/core/triggers/intervaltimer.yaml` — `output`
+- `packs/core/triggers/crontimer.yaml` — `output`
+- `packs/core/triggers/datetimetimer.yaml` — `output`
+- `packs/core/actions/http_request.yaml` — `output_schema`
+- `packs/core/actions/build_pack_envs.yaml` — `output_schema`
+- `packs/core/actions/download_packs.yaml` — `output_schema`
+- `packs/core/actions/get_pack_dependencies.yaml` — `output_schema`
+- `packs/core/actions/register_packs.yaml` — `output_schema`
+- `packs/core/workflows/install_packs.yaml` — `output_schema`
+- `packs/examples/actions/list_example.yaml` — `output_schema`
+
+Nested structures (e.g., `items: { type: object, properties: { ... } }` within array parameters) remain unchanged — only the top-level wrapper was converted.
+
+### Web UI (6 files)
+
+- **`ParamSchemaForm.tsx`** — Removed legacy JSON Schema branch from `extractProperties()`. Removed `extractJsonSchemaProperties()` (no longer needed). Single `extractProperties()` handles all schema types.
+- **`ParamSchemaDisplay.tsx`** — Updated doc comment, tightened `schema` prop type from `ParamSchema | any` to `ParamSchema`.
+- **`SchemaBuilder.tsx`** — Removed legacy JSON Schema reading from both `useEffect` initializer and `handleRawJsonChange`. Only reads/writes flat format.
+- **`PackForm.tsx`** — Updated `confSchema` initial state from JSON Schema to `{}`. Updated `hasSchemaProperties` check (no longer looks for `.properties` sub-key). Updated config sync logic, validation, schema examples (API/Database/Webhook examples now use flat format with `secret` and `required` inline), and `ParamSchemaForm` pass-through (passes `confSchema` directly instead of `confSchema.properties`).
+- **`TriggerForm.tsx`** — Updated `paramSchema` and `outSchema` initial states from JSON Schema to `{}`.
+- **`TriggersPage.tsx`** — Uses `extractProperties()` for both `param_schema` and `out_schema`.
+
+### Backend Rust (5 files)
+
+- **`crates/api/src/validation/params.rs`** — Added `flat_to_json_schema()` function that converts flat format to JSON Schema internally before passing to `jsonschema::Validator`. Updated `validate_trigger_params()` and `validate_action_params()` to call the converter. Converted all 29 test schemas from JSON Schema to flat format. Added 4 unit tests for `flat_to_json_schema()` and 1 test for secret field validation.
+- **`crates/api/src/dto/action.rs`** — Updated `out_schema` doc comment and utoipa example.
+- **`crates/api/src/dto/trigger.rs`** — Updated `out_schema` and sensor `param_schema` doc comments and utoipa examples.
+- **`crates/api/src/dto/workflow.rs`** — Updated `out_schema` doc comment and utoipa example.
+- **`crates/api/src/dto/pack.rs`** — Updated `conf_schema` doc comment and utoipa example.
+- **`crates/api/src/dto/inquiry.rs`** — Updated `response_schema` doc comment and utoipa example.
+
+### Documentation
+
+- **`AGENTS.md`** — Updated "Parameter Schema Format" section to "Schema Format (Unified)", reflecting that all schema types now use the same flat format.
+
+## Test Results
+
+- All 29 backend validation tests pass (converted to flat format schemas)
+- TypeScript compilation clean (zero errors)
+- Rust workspace compilation clean (zero warnings)
+
+## Format Reference
+
+**Before** (JSON Schema for out_schema/conf_schema):
+```yaml
+output:
+  type: object
+  properties:
+    fired_at:
+      type: string
+      format: date-time
+  required:
+    - fired_at
+```
+
+**After** (unified flat format):
+```yaml
+output:
+  fired_at:
+    type: string
+    format: date-time
+    required: true
+    secret: false  # optional, can mark outputs as secret too
+```