Quickback Docs

Schema Format Reference

Complete TypeScript type definitions for the schema-registry.json format.

Schema Format Reference

The schema registry is a JSON file with a well-defined structure. Below are the complete TypeScript type definitions used by both the compiler (to generate) and the CMS (to consume).

SchemaRegistry

The top-level type:

interface SchemaRegistry {
  generatedAt: string;
  generatedBy: string;
  version: string;
  singleTenant?: boolean;
  features: Record<string, string[]>;
  tables: Record<string, TableMeta>;
  tablesByFeature: Record<string, string[]>;
  pages: Record<string, PageMeta>;
  pagesByFeature: Record<string, string[]>;
}
FieldDescription
generatedAtISO 8601 timestamp of when the registry was generated
generatedByAlways "quickback-compiler"
versionCompiler version string
singleTenantWhen true, project has no organization layer (single-tenant mode)
featuresMap of feature name to array of source file names
tablesMap of camelCase table name to full table metadata
tablesByFeatureMap of feature name to array of table names in that feature
pagesMap of page slug to full page metadata
pagesByFeatureMap of feature name to array of page slugs in that feature

TableMeta

Full metadata for a single table:

interface TableMeta {
  name: string;
  dbName: string;
  feature: string;
  columns: ColumnMeta[];
  firewall: Record<string, unknown>;
  crud: Record<string, CrudConfig>;
  guards: GuardsConfig;
  masking: Record<string, MaskingRule>;
  views: Record<string, ViewConfig>;
  validation: Record<string, ValidationRule>;
  actions: ActionMeta[];
  displayColumn?: string;
  defaultSort?: { field: string; order: 'asc' | 'desc' };
  inputHints?: Record<string, string>;
  layouts?: Record<string, CmsLayout>;
  internal?: boolean;
}
FieldDescription
namecamelCase table name (e.g., "accountCode")
dbNameSnake_case SQL table name (e.g., "account_code")
featureParent feature name (e.g., "accounting")
columnsOrdered array of column metadata
firewallTenant isolation config (organization, owner, softDelete, exception)
crudPer-operation (create, read, update, delete) access config
guardsField-level create/update/immutable/protected rules
maskingPer-field masking rules keyed by column name
viewsNamed column projections keyed by view name
validationPer-field validation rules keyed by column name
actionsArray of action definitions for this table
displayColumnColumn used as human-readable label (auto-detected or explicit)
defaultSortDefault sort for CMS table list view (e.g., { field: "createdAt", order: "desc" })
inputHintsMap of column name to preferred CMS input type (e.g., "richtext", "select", "textarea", "checkbox")
layoutsNamed record page layouts keyed by layout name (see CmsLayout below)
internalWhen true, table is hidden from CMS sidebar

ColumnMeta

Metadata for a single column:

interface ColumnMeta {
  name: string;
  dbName: string;
  type: "text" | "integer" | "real" | "blob";
  mode?: "boolean";
  primaryKey: boolean;
  notNull: boolean;
  defaultValue?: string | number | boolean;
  fkTarget?: string;
}
FieldDescription
namecamelCase property name
dbNameSnake_case SQL column name
typeSQLite storage type
modeWhen "boolean", an integer column represents true/false
primaryKeyWhether this column is the primary key
notNullWhether the column has a NOT NULL constraint
defaultValueStatic default value (strings, numbers, or booleans)
fkTargetTarget table name for FK columns (e.g., "contact" for a vendorId column)

CRUDConfig

Per-operation access control:

interface CrudConfig {
  access?: AccessRule;
  mode?: string;
}

interface AccessRule {
  roles?: string[];
  or?: Array<{
    roles?: string[];
    record?: Record<string, unknown>;
  }>;
  record?: Record<string, unknown>;
}
FieldDescription
access.rolesArray of roles allowed for this operation
access.orAlternative access conditions (any must match)
access.recordRecord-level conditions for access
modeOperation mode (e.g., "batch" for bulk create)

GuardsConfig

Field-level control for create and update operations:

interface GuardsConfig {
  createable: string[];
  updatable: string[];
  immutable: string[];
  protected: Record<string, string[]>;
}
FieldDescription
createableFields that can be set during record creation
updatableFields that can be modified on existing records
immutableFields that can be set on create but never changed
protectedFields only modifiable via named actions (field name to action names)

ActionMeta

Metadata for a custom action:

interface ActionMeta {
  name: string;
  description: string;
  inputFields: ActionInputField[];
  access?: {
    roles: string[];
    record?: Record<string, unknown>;
  };
  standalone?: boolean;
  path?: string;
  method?: string;
  responseType?: string;
  sideEffects?: string;
  cms?: CmsConfig;
}

interface CmsConfig {
  label?: string;
  icon?: string;
  confirm?: string | boolean;
  destructive?: boolean;
  category?: string;
  hidden?: boolean;
  successMessage?: string;
  onSuccess?: 'refresh' | 'redirect:list' | 'close';
  order?: number;
}

interface ActionInputField {
  name: string;
  type: string;
  required: boolean;
  default?: unknown;
}
FieldDescription
nameAction identifier (e.g., "approve", "applyPayment")
descriptionHuman-readable description shown in dialog
inputFieldsArray of input field definitions
access.rolesRoles allowed to execute this action
access.recordRecord conditions (e.g., { status: { equals: "pending" } })
standaloneWhen true, action is not tied to a specific record
pathCustom API path (overrides default)
methodHTTP method (defaults to POST)
responseType"file" for download responses
sideEffects"sync" for actions with synchronous side effects
cmsOptional CMS rendering metadata (label, icon, confirm, destructive, category, hidden, successMessage, onSuccess, order)

ActionInputField

FieldDescription
nameField identifier
typeZod type string: "string", "number", "boolean", "array<string>"
requiredWhether the field must be provided
defaultDefault value pre-filled in the form

ViewConfig

Named column projection with access control:

interface ViewConfig {
  fields: string[];
  access: AccessRule;
}
FieldDescription
fieldsArray of column names to include in this view
accessRole-based access rules (same shape as CrudConfig access)

CmsLayout

Named record page layout with ordered sections:

interface CmsLayout {
  sections: CmsLayoutSection[];
}

interface CmsLayoutSection {
  label: string;
  fields: string[];
  columns?: 1 | 2;
  collapsed?: boolean;
}
FieldDescription
sectionsOrdered array of field sections

CmsLayoutSection

FieldDescription
labelSection header text
fieldsArray of column names to display in this section
columns1 (default) or 2 for two-column field layout
collapsedWhen true, section starts collapsed with a toggle to expand

Fields not assigned to any section in the active layout are collected into an "Other Fields" section.

MaskingRule

Per-field data masking:

interface MaskingRule {
  type: "email" | "phone" | "ssn" | "redact";
  show: {
    roles: string[];
    or?: string;
  };
}
FieldDescription
typeMasking pattern to apply
show.rolesRoles that see the unmasked value
show.orAlternative condition for showing unmasked value

Masking Patterns

TypeInputOutput
emailjohn@acme.comj***@acme.com
phone(555) 123-4567***-***-4567
ssn123-45-6789***-**-6789
redactAny string------

ValidationRule

Per-field validation constraints:

interface ValidationRule {
  minLength?: number;
  maxLength?: number;
  min?: number;
  max?: number;
  enum?: string[];
  email?: boolean;
}
FieldDescription
minLengthMinimum string length
maxLengthMaximum string length
minMinimum numeric value
maxMaximum numeric value
enumArray of allowed string values
emailWhen true, validates email format

PageMeta

Full metadata for a custom page:

interface PageMeta {
  slug: string;
  title: string;
  description?: string;
  icon?: string;
  feature: string;
  access?: { roles: string[] };
  dataSources: Record<string, PageDataSource>;
  layout: PageLayout;
  matching?: PageMatching;
  pageActions?: Record<string, PageAction>;
}
FieldDescription
slugURL-safe page identifier
titleDisplay title
descriptionHuman-readable description
iconIcon name for sidebar
featureParent feature name
accessRole-based access control
dataSourcesNamed data source bindings
layoutLayout configuration
matchingMatching/reconciliation rules
pageActionsActions triggered from the page

PageDataSource

interface PageDataSource {
  table: string;
  defaultFilters?: Record<string, unknown>;
  defaultSort?: { field: string; order: 'asc' | 'desc' };
  displayColumns?: string[];
}

PageLayout

interface PageLayout {
  type: 'split-panel';
  panels: PagePanel[];
}

interface PagePanel {
  id: string;
  title: string;
  dataSource: string;
  position: 'left' | 'right';
  features?: string[];
}

Panel features can include "drag-source" and "drop-target" for drag-and-drop interactions.

PageMatching

interface PageMatching {
  enabled: boolean;
  rules: MatchingRule[];
  confidenceThreshold?: number;
}

interface MatchingRule {
  name: string;
  weight: number;
  condition: {
    left: string;
    right: string;
    operator: 'abs-equals' | 'within-days' | 'fuzzy-match';
    value?: number;
  };
}
FieldDescription
enabledWhether matching is active
rulesArray of matching rules with weights (0-1)
confidenceThresholdMinimum score to display a match suggestion (0-1, default 0.5)
condition.leftLeft field reference (dataSourceName.fieldName)
condition.rightRight field reference
condition.operatorComparison operator
condition.valueOperator parameter (e.g., max days for within-days)

PageAction

interface PageAction {
  table: string;
  action: string;
  inputMapping: Record<string, string>;
  label?: string;
  icon?: string;
  confirm?: string;
}
FieldDescription
tableTarget table for the action
actionAction name on that table
inputMappingMaps action input fields to data source field references ("dataSourceName.$fieldName")
labelButton label (defaults to action name)
iconButton icon name
confirmConfirmation prompt shown before execution

Next Steps

Actions

Custom actions with auto-generated input forms, access filtering, and side effects warnings.

Components Reference

All CMS React components with their props and descriptions.

On this page

Schema Format ReferenceSchemaRegistryTableMetaColumnMetaCRUDConfigGuardsConfigActionMetaActionInputFieldViewConfigCmsLayoutCmsLayoutSectionMaskingRuleMasking PatternsValidationRulePageMetaPageDataSourcePageLayoutPageMatchingPageActionNext Steps