Defining Schemas

Schemas define the structure of your data through properties, which specify the type, default value, title, description, and constraints for each field.

Key Concepts

Optional

An optional property may be omitted from the input. If missing, it is treated as undefined, allowing the schema to:

Apply default values
Trigger fallback logic
Distinguish between a missing property and a property explicitly set to null

Properties that are not optional must be present.

Nullable

A nullable property accepts null as a valid value. This affects the value, not whether the property must be included.

Optional → controls presence
Nullable → controls allowed values

These flags can be used together or separately.

Default

Default values are only applied to optional properties. If an optional property is omitted, its default is automatically used.

Defaults can be:

Static values
Closures (evaluated lazily)

Creating a Schema

Use Schema::create() to define a new schema:

use Epsicube\Schemas\Schema;

$schema = Schema::create(
    identifier: 'UniqueIdentifier',
    title: 'My Custom Schema',
    description: 'Defines the structure of my data',
    properties: [] // shortcut for ->append()
);

Adding Properties

Append properties to a schema using ->append():

use Epsicube\Schemas\Properties\BooleanProperty;
use Epsicube\Schemas\Properties\StringProperty;

$schema->append([
    'enabled' => BooleanProperty::make()
        ->title('Feature Enabled')
        ->description('Whether this feature is active')
        ->default(true)
        ->optional(),

    'brand-name' => StringProperty::make()
        ->title('Brand Name')
        ->description('The name of your brand or application')
        ->default(fn () => config('app.name'))
        ->optional(),
]);

Each property defines:

Data type (e.g., string, boolean)
Human-readable title
Optional description
Optional default values (static or dynamic)

Built-in Property Types

ArrayProperty — arrays
BooleanProperty — true/false
FloatProperty — decimal numbers
IntegerProperty — whole numbers
ObjectProperty — nested objects
StringProperty — text

EnumProperty

EnumProperty allows a property to accept only specific values, either static or dynamic.

Static Enum

use Epsicube\Schemas\Properties\EnumProperty;
use Epsicube\Schemas\Types\EnumCase;

$schema->append([
    'status' => EnumProperty::make()
        ->title('Status')
        ->description('The current status of the item')
        ->cases(
            new EnumCase('draft', 'Draft'),
            new EnumCase('published', 'Published'),
            new EnumCase('archived', 'Archived')
        )
        ->default('draft')
        ->optional(),
]);

Use cases(...) to define fixed enum values.
Each EnumCase has a value and an optional label.
Defaults can be any valid enum value.

Dynamic Enum

EnumProperty can also generate enum values dynamically, using a closure. The closure is evaluated lazily at runtime:

$schema->append([
    'status' => EnumProperty::make()
        ->title('Status')
        ->dynamic(fn () => array_map(
            fn(StatusEnum $case) => new EnumCase($case->value, $case->name, ['description'=>$case->description()]),
            StatusEnum::cases()
        )),
]);

Use dynamic(fn () => ...) to create enum values from a database, API, or other runtime source.
The closure must return an array of EnumCase.