Skip to main content

Schema System

The QwickApps Schema System provides type-safe data validation, CMS integration patterns, and automatic component configuration for dynamic applications.

Overview​

The schema system bridges the gap between content management systems and React components by providing:

  • Type-safe validation of CMS data at runtime
  • Component schema definitions that describe expected data structure
  • Data transformation patterns for clean content integration
  • Editor guidance for non-technical content creators
  • Automatic prop generation from validated data sources

Core Concepts​

Schema Models​

Schema models define the expected structure and validation rules for component data:

import { Schema, Model, Field, Editor, FieldType } from '@qwickapps/schema';

@Schema('Button', '1.0.0')
export class ButtonModel extends Model {
  @Field()
  @Editor({
    field_type: FieldType.TEXT,
    label: 'Button Label',
    description: 'Text to display on the button',
    placeholder: 'Enter button text...'
  })
  @IsString()
  label!: string;

  @Field()
  @Editor({
    field_type: FieldType.SELECT,
    label: 'Button Variant',
    validation: {
      options: [
        { label: 'Primary', value: 'primary' },
        { label: 'Secondary', value: 'secondary' }
      ]
    }
  })
  @IsIn(['primary', 'secondary'])
  variant?: 'primary' | 'secondary';
}

Data Providers​

Data providers fetch and validate content from various sources:

import { JsonDataProvider, CachedDataProvider } from '@qwickapps/schema';

// Simple JSON data provider
const jsonProvider = new JsonDataProvider({
  data: {
    'buttons.cta': [{
      label: 'Get Started',
      variant: 'primary'
    }]
  }
});

// Cached provider for performance
const cachedProvider = new CachedDataProvider(jsonProvider, {
  maxSize: 100,
  defaultTTL: 60000
});

Schema Validation​

Runtime validation ensures content meets component requirements:

// Automatic validation in components
<Button dataSource="buttons.cta" />

// Manual validation with hooks
const buttonData = useDataBinding<ButtonModel>(
  'buttons.cta',
  { label: 'Fallback', variant: 'primary' },
  ButtonModel
);

Data Flow​

  1. CMS Content → Data provider loads content from external source
  2. Schema Validation → Runtime validation against component schema
  3. Type Safety → TypeScript ensures correct prop types
  4. Component Rendering → Validated data populates component props
  5. Error Handling → Graceful fallbacks for invalid or missing data

Key Features​

Type Safety​

  • Runtime validation of CMS data
  • TypeScript integration for development
  • Automatic error detection and reporting
  • Graceful degradation for invalid content

CMS Integration​

  • Works with any headless CMS (Strapi, Contentful, WordPress)
  • REST API and GraphQL support
  • Custom data provider implementations
  • Flexible content transformation patterns

Performance​

  • Built-in caching mechanisms
  • Lazy loading of schema definitions
  • Efficient re-validation strategies
  • Memory optimization for large datasets

Developer Experience​

  • Clear error messages and debugging info
  • IDE integration with TypeScript
  • Hot reloading during development
  • Comprehensive testing utilities

Quick Start​

1. Define Component Schema​

@Schema('MyComponent', '1.0.0')
export class MyComponentModel extends Model {
  @Field()
  @Editor({
    field_type: FieldType.TEXT,
    label: 'Title'
  })
  @IsString()
  title!: string;
}

2. Setup Data Provider​

const dataProvider = new JsonDataProvider({
  data: {
    'my.content': [{
      title: 'Hello World'
    }]
  }
});

3. Use in Components​

function MyComponent({ dataSource }: { dataSource: string }) {
  const data = useDataBinding<MyComponentModel>(
    dataSource,
    { title: 'Default Title' },
    MyComponentModel
  );
  
  return <h1>{data.title}</h1>;
}

// Usage
<MyComponent dataSource="my.content" />

Advanced Topics​

Next Steps​