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

# Schema Structure

> Complete reference for Salesive form schema structure

The Salesive form schema follows a hierarchical structure: **Pages** → **Sections** → **Fields**. This organization helps create intuitive and maintainable configuration forms.

## Schema Hierarchy

```
Form Schema (salesive.form.json)
  └── Pages[]
       └── Sections[]
            └── Fields[]
```

## Root Schema

The root of your schema file contains an array of pages:

```json theme={null}
{
    "pages": []
}
```

## Page Object

Pages are the top-level organizational unit in your form.

### Structure

```json theme={null}
{
    "page": "string",
    "title": "string",
    "description": "string",
    "sections": []
}
```

### Properties

<ParamField path="page" type="string" required>
  Unique identifier for the page. Use lowercase letters, numbers, and hyphens
  only. **Example:** `"home"`, `"about-us"`, `"contact"`
</ParamField>

<ParamField path="title" type="string" required>
  Display name shown in the form UI. Should be user-friendly and descriptive.
  **Example:** `"Home Page"`, `"About Us Page"`, `"Contact Information"`
</ParamField>

<ParamField path="description" type="string">
  Optional explanation of what this page configures. Helps users understand
  the purpose. **Example:** `"Configure your homepage content and layout"`
</ParamField>

<ParamField path="sections" type="array" required>
  Array of section objects containing related field groups.
</ParamField>

### Example

```json theme={null}
{
    "page": "home",
    "title": "Home Page",
    "description": "Configure your home page content",
    "sections": [
        // sections go here
    ]
}
```

## Section Object

Sections group related fields within a page for better organization.

### Structure

```json theme={null}
{
    "id": "string",
    "title": "string",
    "description": "string",
    "fields": []
}
```

### Properties

<ParamField path="id" type="string" required>
  Unique identifier for the section within its page. Use lowercase with
  hyphens. **Example:** `"hero"`, `"contact-info"`, `"brand-colors"`
</ParamField>

<ParamField path="title" type="string" required>
  Section heading displayed to users. Should clearly indicate the content
  group. **Example:** `"Hero Section"`, `"Contact Information"`, `"Brand
        Colors"`
</ParamField>

<ParamField path="description" type="string">
  Optional helper text explaining what fields in this section control.
  **Example:** `"Primary hero messaging and banners"`
</ParamField>

<ParamField path="fields" type="array" required>
  Array of field objects representing form inputs.
</ParamField>

### Example

```json theme={null}
{
    "id": "hero",
    "title": "Hero Section",
    "description": "Main banner and headline content",
    "fields": [
        // fields go here
    ]
}
```

## Field Object

Fields are the actual form inputs where users enter configuration data.

### Base Structure

All fields share common properties:

```json theme={null}
{
    "id": "string",
    "type": "string",
    "label": "string",
    "description": "string",
    "default": "any",
    "required": "boolean"
}
```

### Common Properties

<ParamField path="id" type="string" required>
  Unique identifier for the field. This becomes the variable name in
  `salesive.config.json`. Use camelCase for consistency with JavaScript
  conventions. **Example:** `"heroTitle"`, `"primaryColor"`, `"phoneNumber"`
</ParamField>

<ParamField path="type" type="string" required>
  Field type determining the input component and data format. **Options:**
  `"text"`, `"media"`, `"color"`, `"select"`
</ParamField>

<ParamField path="label" type="string" required>
  Display label shown above the field. Should be clear and concise.
  **Example:** `"Hero Title"`, `"Primary Color"`, `"Phone Number"`
</ParamField>

<ParamField path="description" type="string">
  Optional helper text providing additional context or instructions.
  **Example:** `"Upload or select hero banner images"`
</ParamField>

<ParamField path="default" type="any">
  Default value for the field. Type depends on the field type. - Text fields:
  `"string"` - Color fields: `"#hexcode"` - Media fields: `"url"` or `["url1",
        "url2"]` - Select fields: `"option value"`
</ParamField>

<ParamField path="required" type="boolean">
  Whether the field must be filled before form submission. **Default:**
  `false`
</ParamField>

### Type-Specific Properties

Different field types have additional properties:

#### Text Fields

```json theme={null}
{
    "id": "heroTitle",
    "type": "text",
    "inputType": "text",
    "label": "Hero Title",
    "placeholder": "Enter hero heading",
    "default": "Welcome to Our Store",
    "required": true
}
```

<ParamField path="inputType" type="string" required>
  HTML input type: `"text"`, `"textarea"`, `"email"`, `"tel"`, `"url"`,
  `"number"`
</ParamField>

<ParamField path="placeholder" type="string">
  Placeholder text shown in empty inputs
</ParamField>

#### Media Fields

```json theme={null}
{
    "id": "heroBanner",
    "type": "media",
    "mediaType": "image",
    "label": "Hero Banner",
    "description": "Upload hero banner images",
    "default": ["https://example.com/image1.jpg"],
    "required": true,
    "multiple": true,
    "minItems": 1,
    "maxItems": 5
}
```

<ParamField path="mediaType" type="string" required>
  Type of media: `"image"`, `"video"`, `"file"`
</ParamField>

<ParamField path="multiple" type="boolean">
  Allow multiple file uploads **Default:** `false`
</ParamField>

<ParamField path="minItems" type="number">
  Minimum number of items required (when `multiple` is true)
</ParamField>

<ParamField path="maxItems" type="number">
  Maximum number of items allowed (when `multiple` is true)
</ParamField>

#### Color Fields

```json theme={null}
{
    "id": "primaryColor",
    "type": "color",
    "label": "Primary Brand Color",
    "default": "#0d65d9",
    "required": true
}
```

Color fields use a color picker input and store values as hex codes.

#### Select Fields

```json theme={null}
{
    "id": "layoutStyle",
    "type": "select",
    "selectType": "text",
    "label": "Layout Style",
    "description": "Choose the layout for this section",
    "default": "grid",
    "required": true,
    "multiple": false,
    "options": [
        {
            "label": "Grid Layout",
            "value": "grid"
        },
        {
            "label": "List Layout",
            "value": "list"
        }
    ]
}
```

<ParamField path="selectType" type="string" required>
  Data type: `"text"`, `"number"`, `"boolean"`
</ParamField>

<ParamField path="multiple" type="boolean">
  Allow multiple selections **Default:** `false`
</ParamField>

<ParamField path="options" type="array" required>
  Array of option objects with `label` and `value` properties
</ParamField>

## Complete Example

Here's a complete schema demonstrating all elements:

```json theme={null}
{
    "pages": [
        {
            "page": "home",
            "title": "Home Page",
            "description": "Configure your home page",
            "sections": [
                {
                    "id": "hero",
                    "title": "Hero Section",
                    "description": "Main banner content",
                    "fields": [
                        {
                            "id": "heroTitle",
                            "type": "text",
                            "inputType": "text",
                            "label": "Hero Title",
                            "placeholder": "Enter hero heading",
                            "default": "Welcome to Our Store",
                            "required": true
                        },
                        {
                            "id": "heroImage",
                            "type": "media",
                            "mediaType": "image",
                            "label": "Hero Background",
                            "description": "Upload hero banner",
                            "required": true
                        }
                    ]
                },
                {
                    "id": "branding",
                    "title": "Brand Colors",
                    "description": "Your brand color palette",
                    "fields": [
                        {
                            "id": "primaryColor",
                            "type": "color",
                            "label": "Primary Color",
                            "default": "#0d65d9",
                            "required": true
                        },
                        {
                            "id": "secondaryColor",
                            "type": "color",
                            "label": "Secondary Color",
                            "default": "#64748b",
                            "required": true
                        }
                    ]
                }
            ]
        }
    ]
}
```

## Best Practices

<Tip>
  **Naming Conventions** - Use camelCase for field IDs: `heroTitle`,
  `primaryColor` - Use kebab-case for page and section IDs: `home`,
  `about-us`, `hero-section` - Keep IDs descriptive but concise
</Tip>

<Warning>
  **ID Uniqueness** Field IDs must be unique across your entire schema, as
  they become variable names in `salesive.config.json`. Using duplicate IDs
  will cause conflicts when accessing variables in your theme.
</Warning>

<Check>
  **Organization Tips** - Group related fields into logical sections - Use
  clear, user-friendly labels and descriptions - Provide sensible default
  values - Mark essential fields as required
</Check>

## Validation

The Form Builder automatically validates your schema:

* Ensures required properties are present
* Checks for duplicate IDs
* Validates field type configurations
* Confirms proper JSON syntax

<Card title="Next: Field Types" icon="arrow-right" href="/form-builder/field-types">
  Learn about all available field types and their specific options
</Card>