> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/BintzGavin/helios/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema

> Schema validation utilities for component props in Helios

## PropType

Supported property types for schema validation.

```typescript theme={null}
type PropType =
  | 'string'
  | 'number'
  | 'boolean'
  | 'object'
  | 'array'
  | 'color'
  | 'image'
  | 'video'
  | 'audio'
  | 'font'
  | 'model'
  | 'json'
  | 'shader'
  | 'int8array'
  | 'uint8array'
  | 'uint8clampedarray'
  | 'int16array'
  | 'uint16array'
  | 'int32array'
  | 'uint32array'
  | 'float32array'
  | 'float64array';
```

## PropDefinition

Defines the schema for a single property.

```typescript theme={null}
interface PropDefinition {
  type: PropType;
  optional?: boolean;
  default?: any;
  minimum?: number;
  maximum?: number;
  minItems?: number;
  maxItems?: number;
  minLength?: number;
  maxLength?: number;
  enum?: (string | number)[];
  label?: string;
  description?: string;
  step?: number;
  format?: string;
  pattern?: string;
  accept?: string[];
  group?: string;
  items?: PropDefinition;
  properties?: HeliosSchema;
}
```

<ResponseField name="type" type="PropType" required>
  The expected type of the property
</ResponseField>

<ResponseField name="optional" type="boolean">
  Whether the property is optional. Default: `false`
</ResponseField>

<ResponseField name="default" type="any">
  Default value if property is not provided
</ResponseField>

<ResponseField name="minimum" type="number">
  Minimum value for number types
</ResponseField>

<ResponseField name="maximum" type="number">
  Maximum value for number types
</ResponseField>

<ResponseField name="minItems" type="number">
  Minimum number of items for array and typed array types
</ResponseField>

<ResponseField name="maxItems" type="number">
  Maximum number of items for array and typed array types
</ResponseField>

<ResponseField name="minLength" type="number">
  Minimum string length for string types
</ResponseField>

<ResponseField name="maxLength" type="number">
  Maximum string length for string types
</ResponseField>

<ResponseField name="enum" type="(string | number)[]">
  Allowed values for the property
</ResponseField>

<ResponseField name="label" type="string">
  Human-readable label for UI rendering
</ResponseField>

<ResponseField name="description" type="string">
  Description of the property
</ResponseField>

<ResponseField name="step" type="number">
  Step increment for number inputs
</ResponseField>

<ResponseField name="format" type="string">
  Format hint for specialized inputs
</ResponseField>

<ResponseField name="pattern" type="string">
  Regular expression pattern for string validation
</ResponseField>

<ResponseField name="accept" type="string[]">
  Accepted file extensions for asset types
</ResponseField>

<ResponseField name="group" type="string">
  Group name for organizing properties in UI
</ResponseField>

<ResponseField name="items" type="PropDefinition">
  Schema for array items (when type is 'array')
</ResponseField>

<ResponseField name="properties" type="HeliosSchema">
  Nested schema for object properties (when type is 'object')
</ResponseField>

## HeliosSchema

A schema is a record mapping property names to their definitions.

```typescript theme={null}
type HeliosSchema = Record<string, PropDefinition>;
```

## validateSchema

Validates that a schema definition is well-formed.

```typescript theme={null}
function validateSchema(schema: HeliosSchema | undefined, parentKey?: string): void
```

<ParamField path="schema" type="HeliosSchema | undefined" required>
  Schema to validate
</ParamField>

<ParamField path="parentKey" type="string">
  Parent key for nested validation (used internally for error messages)
</ParamField>

### Example

```typescript theme={null}
import { validateSchema } from '@helios-project/core';

const schema = {
  title: {
    type: 'string',
    minLength: 1,
    maxLength: 100,
    default: 'Untitled'
  },
  color: {
    type: 'color',
    default: '#ff0000'
  },
  count: {
    type: 'number',
    minimum: 0,
    maximum: 100
  }
};

// Validates successfully
validateSchema(schema);

// Invalid schema - pattern on non-string
const invalid = {
  count: {
    type: 'number',
    pattern: '^\\d+$' // Error! pattern only valid for strings
  }
};

validateSchema(invalid); // Throws HeliosError
```

### Errors

Throws `HeliosError` with code `INVALID_SCHEMA` if:

* Pattern is defined on non-string types
* Pattern regex is invalid
* Accept is defined on incompatible types
* minItems/maxItems is negative or inconsistent
* minLength/maxLength is negative or inconsistent
* Default value doesn't match the schema constraints

## validateProps

Validates component props against a schema.

```typescript theme={null}
function validateProps<T = Record<string, any>>(props: T, schema?: HeliosSchema): T
```

<ParamField path="props" type="T" required>
  Props object to validate
</ParamField>

<ParamField path="schema" type="HeliosSchema">
  Schema to validate against. If not provided, props are returned unchanged.
</ParamField>

<ResponseField name="return" type="T">
  Validated props object with defaults applied and extra props preserved
</ResponseField>

### Example

```typescript theme={null}
import { validateProps } from '@helios-project/core';

const schema = {
  title: {
    type: 'string',
    minLength: 1,
    default: 'Untitled'
  },
  color: {
    type: 'color'
  },
  count: {
    type: 'number',
    minimum: 0,
    maximum: 100,
    optional: true
  }
};

// Valid props
const props = validateProps(
  { color: '#ff0000' },
  schema
);
console.log(props);
// { title: 'Untitled', color: '#ff0000' }

// Missing required prop
validateProps({}, schema);
// Throws HeliosError: Missing required prop: color

// Invalid type
validateProps({ color: 123 }, schema);
// Throws HeliosError: Invalid type for prop 'color'

// Out of range
validateProps({ color: '#ff0000', count: 150 }, schema);
// Throws HeliosError: Prop 'count' must be <= 100

// Nested object validation
const nestedSchema = {
  user: {
    type: 'object',
    properties: {
      name: { type: 'string' },
      age: { type: 'number', minimum: 0 }
    }
  }
};

const nested = validateProps(
  { user: { name: 'Alice', age: 30 } },
  nestedSchema
);

// Array validation
const arraySchema = {
  tags: {
    type: 'array',
    items: { type: 'string' },
    minItems: 1,
    maxItems: 5
  }
};

const withArray = validateProps(
  { tags: ['video', 'animation'] },
  arraySchema
);
```

### Behavior

* **Required props**: Props without `optional: true` must be provided or have a default
* **Defaults**: Applied when prop is undefined
* **Extra props**: Props not in schema are preserved in the output
* **Nested validation**: Objects and arrays are validated recursively
* **Type coercion**: No automatic coercion; types must match exactly

### Errors

Throws `HeliosError` with code `INVALID_INPUT_PROPS` if:

* Required prop is missing and has no default
* Prop type doesn't match schema
* Number is outside minimum/maximum range
* String length is outside minLength/maxLength range
* Array length is outside minItems/maxItems range
* String doesn't match pattern
* Value is not in enum
* Color string is invalid
* File extension doesn't match accept list