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

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):

output:
  type: object
  properties:
    fired_at:
      type: string
      format: date-time
  required:
    - fired_at

After (unified flat format):

output:
  fired_at:
    type: string
    format: date-time
    required: true
    secret: false  # optional, can mark outputs as secret too