DataViews

A DataViewSpec describes how data should be queried, filtered, sorted, and presented to users. Runtime adapters execute optimized database queries and serve list views, detail views, and search interfaces while respecting policy constraints.

Core concepts

Example DataViewSpec

Here's a DataView for listing orders in TypeScript:

import { defineDataView } from '@contractspec/lib.contracts-spec';
import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';

export const OrderList = defineDataView({
  meta: {
    key: 'order.list',
    version: '1.0.0',
    description: 'List of recent orders',
  },
  source: {
    type: 'database',
    table: 'orders',
  },
  fields: [
    { name: 'orderId', type: 'uuid', sortable: true },
    { name: 'customerName', type: 'string', searchable: true },
    { name: 'total', type: 'number', sortable: true },
    { 
      name: 'status', 
      type: 'enum', 
      values: ['pending', 'processing', 'shipped'],
      filterable: true 
    },
    { 
      name: 'createdAt', 
      type: 'timestamp', 
      sortable: true, 
      defaultSort: 'desc' 
    },
  ],
  filters: [
    { name: 'status', field: 'status', operator: 'in' },
    { name: 'dateRange', field: 'createdAt', operator: 'between' },
    { name: 'minTotal', field: 'total', operator: 'gte' },
  ],
  pagination: {
    type: 'cursor',
    defaultPageSize: 50,
    maxPageSize: 200,
  },
});

Policy integration

DataViews automatically enforce PolicySpecs. If a user doesn't have permission to see certain fields, those fields are automatically filtered out or redacted. If a user can only see their own data, the query is automatically scoped.

This means you define the data view once, and it works correctly for all users based on their permissions—no need to write separate queries for different roles.

Served outputs

From a DataViewSpec, ContractSpec serves:

• Database queries – Optimized SQL or NoSQL queries executed at runtime
• API endpoints – RESTful or GraphQL endpoints for fetching data
• UI components – List views, tables, cards, and detail views
• Search interfaces – Full-text search with autocomplete
• Export functions – CSV, JSON, or Excel exports

Best practices

• Only expose fields that users actually need—this improves performance and security.
• Use appropriate indexes for sortable and filterable fields.
• Set reasonable pagination limits to prevent performance issues.
• Use aggregations sparingly—they can be expensive on large datasets.
• Test DataViews with realistic data volumes to ensure they perform well.