UniverseDataController Schema Enhancements

Specification for entity schema management endpoints added to support Flow Builder (Phase 2)

UniverseDataController Schema Enhancements

Purpose

The Flow Builder (Phase 2) needs to let users define entity schemas (e.g., "Product" with name, price, description) and auto-generate CRUD flows against those entities. The backend needs endpoints to:

  1. Define a schema for a collection (field names, types, validation rules)
  2. List all defined schemas in a universe
  3. Retrieve a single schema
  4. Update/delete schemas

New Endpoints

All endpoints are under the existing UniverseDataController route prefix: /api/spaces/:spaceId/universes/:universeId/

1. Define/Update Schema

POST /api/spaces/:spaceId/universes/:universeId/data/schemas

Body:

{
  "collection": "products",
  "displayName": "Products",
  "description": "Product catalog for the store",
  "fields": [
    {
      "name": "name",
      "type": "string",
      "required": true,
      "label": "Product Name",
      "validation": { "minLength": 1, "maxLength": 200 }
    },
    {
      "name": "price",
      "type": "number",
      "required": true,
      "label": "Price",
      "validation": { "min": 0 }
    },
    {
      "name": "description",
      "type": "string",
      "required": false,
      "label": "Description"
    },
    {
      "name": "category",
      "type": "string",
      "required": false,
      "label": "Category",
      "validation": { "enum": ["electronics", "clothing", "food", "other"] }
    },
    {
      "name": "inStock",
      "type": "boolean",
      "required": false,
      "label": "In Stock",
      "defaultValue": true
    }
  ]
}

Response: { success: true, schema: { ... } }

2. List All Schemas

GET /api/spaces/:spaceId/universes/:universeId/data/schemas

Response:

{
  "success": true,
  "schemas": [
    { "collection": "products", "displayName": "Products", "fieldCount": 5, "recordCount": 42 },
    { "collection": "orders", "displayName": "Orders", "fieldCount": 8, "recordCount": 156 }
  ]
}

3. Get Single Schema

GET /api/spaces/:spaceId/universes/:universeId/data/schemas/:collection

Response: Full schema object with all fields.

4. Delete Schema

DELETE /api/spaces/:spaceId/universes/:universeId/data/schemas/:collection

Deletes the schema definition. Does NOT delete the collection data.

Data Types

The EntityFieldType supports:

Type MongoDB Equivalent Flow Builder Port Type
string String string
number Number (Double) number
boolean Boolean boolean
date Date string (ISO)
object Object object
array Array array
reference ObjectId (ref) string (ID)

Validation Rules

Rule Applies To Example
required All types true / false
minLength / maxLength string { minLength: 1, maxLength: 200 }
min / max number { min: 0, max: 10000 }
enum string { enum: ["a", "b", "c"] }
pattern string { pattern: "^[a-z]+$" }
defaultValue All types Any value matching the field type

Storage

Schemas are stored in the universe_{universeId}_schemas collection within the space database. Each document represents one collection's schema.

Integration with Flow Builder

When a user defines an entity in the Flow Builder:

  1. Frontend calls POST /data/schemas with the schema
  2. Backend creates/updates the schema document
  3. Frontend uses the schema to auto-generate CRUD flow templates via instantiateCrudFlow() from crud-flow-templates.ts
  4. The variable {{collection}} is set to the schema's collection name
  5. The variable {{entityName}} is set to the schema's displayName