Report Schema

The ReportSchema enables creating comprehensive data reports with field aggregation, multiple export formats, and automated scheduling.

Overview

ReportSchema provides:

Field aggregation - Sum, average, count, min, max, distinct
Export formats - PDF, Excel, CSV, JSON, HTML
Scheduled reports - Daily, weekly, monthly, quarterly, yearly
Email distribution - Automatic report delivery
Interactive builder - Report configuration UI
Data filtering - Complex filter criteria

Interactive Examples

Sales Report Header

Report Header with KPIs

Summary section showing key metrics at the top of a report

{
  "type": "stack",
  "spacing": 4,
  "children": [
    {
      "type": "flex",
      "className": "items-center justify-between",
      "children": [
        {
          "type": "stack",
          "spacing": 1,
          "children": [
            {
              "type": "text",
              "content": "Quarterly Sales Report",
              "className": "text-xl font-bold"
            },
            {
              "type": "text",
              "content": "Q1 2024 · January - March",
              "className": "text-sm text-muted-foreground"
            }
          ]
        },
        {
          "type": "flex",
          "className": "gap-2",
          "children": [
            {
              "type": "button",
              "label": "PDF",
              "variant": "outline",
              "size": "sm",
              "icon": "file-text"
            },
            {
              "type": "button",
              "label": "Excel",
              "variant": "outline",
              "size": "sm",
              "icon": "table"
            },
            {
              "type": "button",
              "label": "Print",
              "variant": "outline",
              "size": "sm",
              "icon": "printer"
            }
          ]
        }
      ]
    },
    {
      "type": "grid",
      "cols": 4,
      "gap": 4,
      "children": [
        {
          "type": "card",
          "className": "p-4",
          "children": [
            {
              "type": "text",
              "content": "Total Revenue",
              "className": "text-xs text-muted-foreground font-medium uppercase tracking-wider"
            },
            {
              "type": "text",
              "content": "$284,500",
              "className": "text-2xl font-bold mt-1"
            },
            {
              "type": "text",
              "content": "+12.5% vs Q4",
              "className": "text-xs text-green-600 mt-1"
            }
          ]
        },
        {
          "type": "card",
          "className": "p-4",
          "children": [
            {
              "type": "text",
              "content": "Orders",
              "className": "text-xs text-muted-foreground font-medium uppercase tracking-wider"
            },
            {
              "type": "text",
              "content": "1,842",
              "className": "text-2xl font-bold mt-1"
            },
            {
              "type": "text",
              "content": "+8.3% vs Q4",
              "className": "text-xs text-green-600 mt-1"
            }
          ]
        },
        {
          "type": "card",
          "className": "p-4",
          "children": [
            {
              "type": "text",
              "content": "Avg. Order",
              "className": "text-xs text-muted-foreground font-medium uppercase tracking-wider"
            },
            {
              "type": "text",
              "content": "$154.45",
              "className": "text-2xl font-bold mt-1"
            },
            {
              "type": "text",
              "content": "+3.8% vs Q4",
              "className": "text-xs text-green-600 mt-1"
            }
          ]
        },
        {
          "type": "card",
          "className": "p-4",
          "children": [
            {
              "type": "text",
              "content": "Return Rate",
              "className": "text-xs text-muted-foreground font-medium uppercase tracking-wider"
            },
            {
              "type": "text",
              "content": "2.4%",
              "className": "text-2xl font-bold mt-1"
            },
            {
              "type": "text",
              "content": "-0.6% vs Q4",
              "className": "text-xs text-green-600 mt-1"
            }
          ]
        }
      ]
    }
  ]
}

Report Data Table

Report Breakdown Table

Tabular data section with aggregation summaries by region

{
  "type": "card",
  "children": [
    {
      "type": "flex",
      "className": "items-center justify-between mb-4",
      "children": [
        {
          "type": "text",
          "content": "Revenue by Region",
          "className": "font-semibold"
        },
        {
          "type": "badge",
          "label": "5 regions",
          "variant": "secondary"
        }
      ]
    },
    {
      "type": "stack",
      "spacing": 0,
      "children": [
        {
          "type": "flex",
          "className": "items-center gap-4 px-4 py-2 bg-muted text-xs font-medium text-muted-foreground border-b",
          "children": [
            {
              "type": "text",
              "content": "Region",
              "className": "w-36"
            },
            {
              "type": "text",
              "content": "Revenue",
              "className": "w-24"
            },
            {
              "type": "text",
              "content": "Orders",
              "className": "w-20"
            },
            {
              "type": "text",
              "content": "Growth",
              "className": "w-20"
            }
          ]
        },
        {
          "type": "flex",
          "className": "items-center gap-4 px-4 py-3 border-b text-sm",
          "children": [
            {
              "type": "text",
              "content": "North America",
              "className": "w-36 font-medium"
            },
            {
              "type": "text",
              "content": "$125,400",
              "className": "w-24"
            },
            {
              "type": "text",
              "content": "824",
              "className": "w-20"
            },
            {
              "type": "text",
              "content": "+15.2%",
              "className": "w-20 text-green-600"
            }
          ]
        },
        {
          "type": "flex",
          "className": "items-center gap-4 px-4 py-3 border-b text-sm",
          "children": [
            {
              "type": "text",
              "content": "Europe",
              "className": "w-36 font-medium"
            },
            {
              "type": "text",
              "content": "$89,200",
              "className": "w-24"
            },
            {
              "type": "text",
              "content": "562",
              "className": "w-20"
            },
            {
              "type": "text",
              "content": "+10.8%",
              "className": "w-20 text-green-600"
            }
          ]
        },
        {
          "type": "flex",
          "className": "items-center gap-4 px-4 py-3 border-b text-sm",
          "children": [
            {
              "type": "text",
              "content": "Asia Pacific",
              "className": "w-36 font-medium"
            },
            {
              "type": "text",
              "content": "$42,300",
              "className": "w-24"
            },
            {
              "type": "text",
              "content": "298",
              "className": "w-20"
            },
            {
              "type": "text",
              "content": "+22.1%",
              "className": "w-20 text-green-600"
            }
          ]
        },
        {
          "type": "flex",
          "className": "items-center gap-4 px-4 py-3 border-b text-sm",
          "children": [
            {
              "type": "text",
              "content": "Latin America",
              "className": "w-36 font-medium"
            },
            {
              "type": "text",
              "content": "$18,600",
              "className": "w-24"
            },
            {
              "type": "text",
              "content": "108",
              "className": "w-20"
            },
            {
              "type": "text",
              "content": "+5.4%",
              "className": "w-20 text-green-600"
            }
          ]
        },
        {
          "type": "flex",
          "className": "items-center gap-4 px-4 py-3 text-sm",
          "children": [
            {
              "type": "text",
              "content": "Middle East",
              "className": "w-36 font-medium"
            },
            {
              "type": "text",
              "content": "$9,000",
              "className": "w-24"
            },
            {
              "type": "text",
              "content": "50",
              "className": "w-20"
            },
            {
              "type": "text",
              "content": "+18.7%",
              "className": "w-20 text-green-600"
            }
          ]
        }
      ]
    }
  ]
}

Schedule Configuration Preview

Report Scheduling

Configure automated report delivery via email

{
  "type": "card",
  "className": "max-w-lg mx-auto",
  "header": [
    {
      "type": "flex",
      "className": "items-center gap-2",
      "children": [
        {
          "type": "icon",
          "name": "clock",
          "className": "h-5 w-5 text-primary"
        },
        {
          "type": "text",
          "content": "Schedule Settings",
          "className": "font-semibold"
        }
      ]
    }
  ],
  "children": [
    {
      "type": "stack",
      "spacing": 4,
      "children": [
        {
          "type": "stack",
          "spacing": 2,
          "children": [
            {
              "type": "label",
              "label": "Frequency"
            },
            {
              "type": "select",
              "options": [
                {
                  "label": "Monthly",
                  "value": "monthly"
                },
                {
                  "label": "Weekly",
                  "value": "weekly"
                },
                {
                  "label": "Daily",
                  "value": "daily"
                }
              ],
              "defaultValue": "monthly"
            }
          ]
        },
        {
          "type": "stack",
          "spacing": 2,
          "children": [
            {
              "type": "label",
              "label": "Day of Month"
            },
            {
              "type": "input",
              "inputType": "number",
              "placeholder": "1",
              "defaultValue": "1"
            }
          ]
        },
        {
          "type": "stack",
          "spacing": 2,
          "children": [
            {
              "type": "label",
              "label": "Recipients"
            },
            {
              "type": "input",
              "placeholder": "sales-team@company.com"
            }
          ]
        },
        {
          "type": "flex",
          "className": "gap-2",
          "children": [
            {
              "type": "checkbox",
              "id": "pdf",
              "name": "pdf",
              "defaultChecked": true
            },
            {
              "type": "label",
              "htmlFor": "pdf",
              "label": "PDF"
            },
            {
              "type": "checkbox",
              "id": "excel",
              "name": "excel"
            },
            {
              "type": "label",
              "htmlFor": "excel",
              "label": "Excel"
            },
            {
              "type": "checkbox",
              "id": "csv",
              "name": "csv"
            },
            {
              "type": "label",
              "htmlFor": "csv",
              "label": "CSV"
            }
          ]
        },
        {
          "type": "flex",
          "className": "justify-end gap-2 pt-2",
          "children": [
            {
              "type": "button",
              "label": "Cancel",
              "variant": "outline"
            },
            {
              "type": "button",
              "label": "Save Schedule",
              "variant": "default",
              "icon": "save"
            }
          ]
        }
      ]
    }
  ]
}

Basic Usage

import type { ReportSchema } from '@object-ui/types';

const salesReport: ReportSchema = {
  type: 'report',
  title: 'Monthly Sales Report',
  description: 'Sales performance analysis',
  
  fields: [
    {
      name: 'total_sales',
      label: 'Total Sales',
      type: 'number',
      aggregation: 'sum',
      format: 'currency'
    },
    {
      name: 'order_count',
      label: 'Orders',
      type: 'number',
      aggregation: 'count'
    }
  ],
  
  filters: [
    {
      field: 'date',
      operator: 'between',
      values: ['2024-01-01', '2024-01-31']
    }
  ],
  
  showExportButtons: true
};

Properties

Basic Configuration

Property	Type	Description
`type`	`'report'`	Component type identifier (required)
`title`	`string`	Report title
`description`	`string`	Report description
`dataSource`	`DataSource`	Data source configuration

Report Fields

interface ReportField {
  name: string;                    // Field name
  label?: string;                  // Display label
  type?: 'string' | 'number' | 'date' | 'boolean';
  aggregation?: 'sum' | 'avg' | 'min' | 'max' | 'count' | 'distinct';
  format?: string;                 // Display format
  showInSummary?: boolean;         // Show in summary section
  sortOrder?: number;              // Sort order
}

Aggregation Types

sum - Total of all values
avg - Average value
min - Minimum value
max - Maximum value
count - Count of records
distinct - Count of unique values

Filters

interface ReportFilter {
  field: string;
  operator: 'equals' | 'not_equals' | 'contains' | 'greater_than' | 
            'less_than' | 'between' | 'in' | 'not_in';
  value?: any;
  values?: any[];  // For 'between' and 'in' operators
}

Group By

interface ReportGroupBy {
  field: string;
  label?: string;
  sort?: 'asc' | 'desc';
}

Report Sections

Define report structure with sections:

interface ReportSection {
  type: 'header' | 'summary' | 'chart' | 'table' | 'text' | 'page-break';
  title?: string;
  content?: SchemaNode | SchemaNode[];
  chart?: ChartSchema;        // For type='chart'
  columns?: ReportField[];    // For type='table'
  text?: string;              // For type='text'
  visible?: boolean | string; // Visibility condition
}

Export Configuration

interface ReportExportConfig {
  format: 'pdf' | 'excel' | 'csv' | 'json' | 'html';
  filename?: string;
  includeHeaders?: boolean;
  orientation?: 'portrait' | 'landscape';  // PDF only
  pageSize?: 'A4' | 'A3' | 'Letter' | 'Legal';  // PDF only
  options?: Record<string, any>;
}

Scheduling

interface ReportSchedule {
  enabled?: boolean;
  frequency?: 'once' | 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly';
  dayOfWeek?: number;          // For weekly (0-6)
  dayOfMonth?: number;         // For monthly (1-31)
  time?: string;               // HH:mm format
  timezone?: string;
  recipients?: string[];       // Email addresses
  subject?: string;
  body?: string;
  formats?: ReportExportFormat[];  // Formats to attach
}

Complete Example

const comprehensiveReport: ReportSchema = {
  type: 'report',
  title: 'Quarterly Sales Analysis',
  description: 'Comprehensive sales performance analysis by region and product',
  
  // Data source
  dataSource: {
    provider: 'api',
    read: {
      url: '/api/sales',
      method: 'GET'
    }
  },
  
  // Report fields
  fields: [
    {
      name: 'region',
      label: 'Region',
      type: 'string'
    },
    {
      name: 'product',
      label: 'Product',
      type: 'string'
    },
    {
      name: 'revenue',
      label: 'Revenue',
      type: 'number',
      aggregation: 'sum',
      format: 'currency',
      showInSummary: true
    },
    {
      name: 'units_sold',
      label: 'Units Sold',
      type: 'number',
      aggregation: 'sum',
      showInSummary: true
    },
    {
      name: 'avg_price',
      label: 'Average Price',
      type: 'number',
      aggregation: 'avg',
      format: 'currency'
    }
  ],
  
  // Filters
  filters: [
    {
      field: 'date',
      operator: 'between',
      values: ['2024-01-01', '2024-03-31']
    },
    {
      field: 'status',
      operator: 'equals',
      value: 'completed'
    }
  ],
  
  // Grouping
  groupBy: [
    {
      field: 'region',
      label: 'Region',
      sort: 'asc'
    },
    {
      field: 'product',
      label: 'Product',
      sort: 'desc'
    }
  ],
  
  // Report sections
  sections: [
    {
      type: 'header',
      title: 'Executive Summary'
    },
    {
      type: 'summary',
      title: 'Key Metrics'
    },
    {
      type: 'chart',
      title: 'Revenue Trend',
      chart: {
        type: 'chart',
        chartType: 'line',
        data: [],
        series: [
          {
            name: 'Revenue',
            type: 'line',
            dataKey: 'revenue'
          }
        ]
      }
    },
    {
      type: 'table',
      title: 'Detailed Breakdown',
      columns: [
        { name: 'region', label: 'Region' },
        { name: 'product', label: 'Product' },
        { name: 'revenue', label: 'Revenue', aggregation: 'sum' },
        { name: 'units_sold', label: 'Units', aggregation: 'sum' }
      ]
    },
    {
      type: 'page-break'
    },
    {
      type: 'text',
      text: 'Report generated on ${new Date().toLocaleDateString()}'
    }
  ],
  
  // Schedule configuration
  schedule: {
    enabled: true,
    frequency: 'monthly',
    dayOfMonth: 1,
    time: '09:00',
    timezone: 'America/New_York',
    recipients: [
      'sales-team@company.com',
      'management@company.com'
    ],
    subject: 'Monthly Sales Report - ${date}',
    body: 'Please find attached the monthly sales report.',
    formats: ['pdf', 'excel']
  },
  
  // Export configuration
  defaultExportFormat: 'pdf',
  exportConfigs: {
    pdf: {
      format: 'pdf',
      filename: 'sales-report-${date}.pdf',
      orientation: 'landscape',
      pageSize: 'A4',
      includeHeaders: true
    },
    excel: {
      format: 'excel',
      filename: 'sales-report-${date}.xlsx',
      includeHeaders: true
    },
    csv: {
      format: 'csv',
      filename: 'sales-data-${date}.csv',
      includeHeaders: true
    }
  },
  
  // UI options
  showExportButtons: true,
  showPrintButton: true,
  showScheduleButton: true,
  refreshInterval: 300  // Auto-refresh every 5 minutes
};

Report Builder

Use ReportBuilderSchema for interactive report creation:

import type { ReportBuilderSchema } from '@object-ui/types';

const builder: ReportBuilderSchema = {
  type: 'report-builder',
  
  report: {
    // Initial report configuration
  },
  
  dataSources: [
    { provider: 'api', read: { url: '/api/sales' } },
    { provider: 'api', read: { url: '/api/customers' } }
  ],
  
  availableFields: [
    { name: 'revenue', label: 'Revenue', type: 'number' },
    { name: 'units', label: 'Units Sold', type: 'number' }
  ],
  
  showPreview: true,
  onSave: 'handleSaveReport',
  onCancel: 'handleCancel'
};

Report Viewer

Use ReportViewerSchema to display generated reports:

import type { ReportViewerSchema } from '@object-ui/types';

const viewer: ReportViewerSchema = {
  type: 'report-viewer',
  report: salesReport,
  data: reportData,
  showToolbar: true,
  allowExport: true,
  allowPrint: true,
  loading: false
};

Runtime Validation

import { ReportSchema } from '@object-ui/types/zod';

const result = ReportSchema.safeParse(myReport);

if (result.success) {
  console.log('Valid report configuration');
} else {
  console.error('Validation errors:', result.error);
}

Use Cases

ReportSchema is perfect for:

Analytics dashboards - Display key business metrics and KPIs
Business intelligence - Generate insights from operational data
Automated reporting - Schedule regular reports for stakeholders
Data exports - Provide data in multiple formats (PDF, Excel, CSV)
Compliance reporting - Generate audit trails and regulatory reports
Executive summaries - Create high-level overviews for management

Best Practices

Use meaningful aggregations - Choose aggregation types that make sense for the data
Limit field count - Too many fields make reports hard to read
Group logically - Group by dimensions that provide insights
Test exports - Verify all export formats render correctly
Set reasonable schedules - Don't over-email recipients
Include filters - Allow users to customize date ranges
Add summary sections - Provide key metrics at the top

Chart Components - Data visualization
Data Table - Tabular data display
Data Source - Data integration

Report Schema (ReportSchema)