> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heliosrender.com/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;
}
```

**type** `PropType` *required*

The expected type of the property

**optional** `boolean`

Whether the property is optional. Default: `false`

**default** `any`

Default value if property is not provided

**minimum** `number`

Minimum value for number types

**maximum** `number`

Maximum value for number types

**minItems** `number`

Minimum number of items for array and typed array types

**maxItems** `number`

Maximum number of items for array and typed array types

**minLength** `number`

Minimum string length for string types

**maxLength** `number`

Maximum string length for string types

**enum** `(string | number)[]`

Allowed values for the property

**label** `string`

Human-readable label for UI rendering

**description** `string`

Description of the property

**step** `number`

Step increment for number inputs

**format** `string`

Format hint for specialized inputs

**pattern** `string`

Regular expression pattern for string validation

**accept** `string[]`

Accepted file extensions for asset types

**group** `string`

Group name for organizing properties in UI

**items** `PropDefinition`

Schema for array items (when type is 'array')

**properties** `HeliosSchema`

Nested schema for object properties (when type is 'object')

## 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
```

**schema** `HeliosSchema | undefined` *required*

Schema to validate

**parentKey** `string`

Parent key for nested validation (used internally for error messages)

### 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
```

**props** `T` *required*

Props object to validate

**schema** `HeliosSchema`

Schema to validate against. If not provided, props are returned unchanged.

**return** `T`

Validated props object with defaults applied and extra props preserved

### 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.