trustgraph/ai-context/workbench-ui/docs/tech-specs/schema.md

# Schema Support for TrustGraph UI

## Overview

This document specifies the UI work needed to support structured data schemas in TrustGraph. Schemas enable the system to work with structured data (rows in tables/objects) alongside unstructured data processing.

## Schema Representation

Based on the STRUCTURED_DATA.md specification, schemas are stored in TrustGraph's configuration system with:

- **Type**: `schema` (fixed value for all structured data schemas)
- **Key**: Unique schema identifier (e.g., `customer_records`, `transaction_log`)
- **Value**: JSON schema definition

### Schema Structure Example:
```json
{
  "name": "customer_records",
  "description": "Customer information table",
  "fields": [
    {
      "name": "customer_id",
      "type": "string",
      "primary_key": true
    },
    {
      "name": "name",
      "type": "string",
      "required": true
    },
    {
      "name": "email",
      "type": "string",
      "required": true
    },
    {
      "name": "registration_date",
      "type": "timestamp"
    },
    {
      "name": "status",
      "type": "string",
      "enum": ["active", "inactive", "suspended"]
    }
  ],
  "indexes": ["email", "registration_date"]
}
```

### Field Types Supported:
- `string`
- `integer`
- `float`
- `boolean`
- `timestamp`
- `enum` (with predefined values)

### Field Properties:
- `name`: Field identifier
- `type`: Data type
- `primary_key`: Boolean flag for primary key fields
- `required`: Boolean flag for required fields
- `enum`: Array of allowed values for enum types

## Requirements

Based on the Prompts page implementation pattern, the Schema UI should provide:

1. **Schema Management Page**
   - List all schemas in a table view
   - Create new schemas via modal dialog
   - Edit existing schemas
   - Delete schemas with confirmation
   - View schema details in a readable format

2. **UI Components Needed**
   - Main schemas page with table listing
   - Create/Edit schema dialog with form validation
   - Schema field editor (add/remove/edit fields)
   - Field type selector with appropriate options
   - Primary key and index configuration
   - Schema preview/viewer component

3. **State Management**
   - Use React Query for data fetching and mutations
   - Implement CRUD operations following the prompts pattern
   - Handle loading states and error notifications
   - Cache management and invalidation

## Implementation Details

### API Integration Pattern (from Prompts example)

1. **Configuration Keys**
   - Individual schemas: `{ type: "schema", key: "{schema_id}" }`
   - List all schemas by querying all keys with `type: "schema"`

2. **State Management Hook** (`useSchemas`)
   - `getValues("schema")` to list all schemas (returns array of {key, value} objects)
   - `putConfig()` to create/update schemas
   - `deleteConfig()` to remove schemas
   - No need for separate index management

3. **Component Structure**
   - `SchemasPage.tsx` - Main page component
   - `components/schemas/Schemas.tsx` - Container component
   - `components/schemas/SchemasTable.tsx` - List view
   - `components/schemas/SchemaControls.tsx` - Action buttons
   - `components/schemas/EditSchemaDialog.tsx` - Create/Edit form
   - `components/schemas/SchemaViewer.tsx` - Read-only schema display
   - `state/schemas.ts` - React Query hooks
   - `model/schemas-table.tsx` - TypeScript definitions

4. **Field Editor Requirements**
   - Dynamic field list with add/remove capabilities
   - Field property editors:
     - Name (text input)
     - Type (dropdown: string, integer, float, boolean, timestamp, enum)
     - Primary key (checkbox)
     - Required (checkbox)
     - Enum values (list editor, shown only for enum type)
   - Index configuration (multi-select from available fields)

5. **Validation Rules**
   - Schema name: Required, unique
   - At least one field required
   - At least one primary key field
   - Field names must be unique within schema
   - Enum type requires at least one enum value

## Tasks

1. Create schema state management hook (`useSchemas`)
2. Implement SchemasPage and routing
3. Build SchemasTable component with sorting/filtering
4. Create EditSchemaDialog with field editor
5. Add schema validation logic
6. Implement schema viewer component
7. Add TypeScript models and table configurations
8. Integration testing with backend API

## Notes

- Follow the existing Prompts page pattern for consistency
- Use Chakra UI components matching current design system
- Implement proper error handling and user feedback
- Consider adding import/export functionality for schemas
- May need to handle schema versioning in the future
- Implementation is simpler than prompts since we use `getValues("schema")` instead of maintaining a separate index
- Reference the agent-tools implementation pattern which also uses `getValues()` directly