Struct Types

Struct types give names to object-shaped payloads that flow through your workflows. Instead of repeating an anonymous kind: 'object' schema on every port that carries the same payload, you define the shape once as a workspace-scoped struct type and reference it by name.

What a struct type looks like

{
  "id": "sty_abc123",
  "workspaceId": "ws_xyz",
  "name": "ReviewResult",
  "version": 1,
  "fields": [
    { "name": "approved",   "type": { "kind": "boolean" } },
    { "name": "reviewedBy", "type": { "kind": "string" } },
    { "name": "comments",   "type": { "kind": "array", "elementType": { "kind": "string" } } },
    { "name": "score",      "type": { "kind": "number" }, "optional": true }
  ]
}

Field naming rules: non-empty, max 64 chars, must match /^[A-Za-z_][A-Za-z0-9_]*$/. Struct names: non-empty, max 128 chars.

Field types

Each field's type is a PortType - the same type system used for workflow edge port types:

`kind`	Description
`string`	UTF-8 text
`number`	IEEE-754 double
`boolean`	`true` / `false`
`object`	Untyped object (use `schema` for JSON Schema 7 constraints)
`array`	Homogeneous array; set `elementType` for the element type
`union`	Tagged union; set `members` array
`null`	Null literal
`any`	No type constraint
`struct`	Reference to another struct type (by `structRef.id`)

Mark a field optional: true when it may be absent in payloads. Absence defaults to required.

CRUD API

Struct types are scoped per workspace. Cross-workspace access returns 404.

POST /api/workspace/struct-types
Content-Type: application/json
Authorization: Bearer rsk_live_...

{
  "name": "ReviewResult",
  "fields": [
    { "name": "approved",   "type": { "kind": "boolean" } },
    { "name": "reviewedBy", "type": { "kind": "string" } },
    { "name": "score",      "type": { "kind": "number" }, "optional": true }
  ]
}

The server assigns id, workspaceId, and initial version: 1.

GET /api/workspace/struct-types
Authorization: Bearer rsk_live_...

Returns an array of StructTypeDef objects for the authenticated workspace.

PATCH /api/workspace/struct-types/{id}
Content-Type: application/json
Authorization: Bearer rsk_live_...

{
  "fields": [
    { "name": "approved",   "type": { "kind": "boolean" } },
    { "name": "reviewedBy", "type": { "kind": "string" } },
    { "name": "score",      "type": { "kind": "number" }, "optional": true },
    { "name": "tags",       "type": { "kind": "array", "elementType": { "kind": "string" } } }
  ]
}

At least one of name or fields must be present. The server increments version.

DELETE /api/workspace/struct-types/{id}
Authorization: Bearer rsk_live_...

Referencing a struct type on a port

Use kind: 'struct' with a structRef to reference a named type on a group interface port or node output schema:

interface:
  outputs:
    - id: result
      type:
        kind: struct
        structRef:
          id: sty_abc123
          name: ReviewResult   # display hint, not authoritative
          version: 1           # optional - omit to always use latest

Struct types may not appear on group bundle boundary ports (interface.inputs / interface.outputs of a published bundle). Cross-workspace struct resolution is not yet implemented; use kind: 'object' with an inline JSONSchema7 schema on boundary ports instead. Interior node ports within a group may still use struct types.

Validation

validateStructTypeCreate and validateStructTypeUpdate return a discriminated union:

// Success
{ valid: true, data: StructTypeCreateInput }

// Failure
{ valid: false, errors: Array<{ path: string; message: string }> }

Duplicate field names within a struct are a hard error (fields.{idx}.name: "duplicate field name 'score'").

Port Type Editor

In the workflow editor's Port Type Editor, when you add or edit a port on a group interface, a struct type picker lets you search your workspace's struct types by name and insert a kind: 'struct' reference. This provides nominal typing and editor auto-complete for downstream SchemaPicker fields.

Port Types - full port type system
Groups - using struct types on group interface ports
Group Bundles - struct type restriction at bundle boundary