Blueprint

Schema

What is the schema?
The schema defines all the components that are available to the theme:
Component
Description
Templates
The major page types (e.g. homepage, product page).
Sections
Reusable layout components that can contain blocks.
Blocks
Reusable items available for use inside sections.
Settings
Configurable options for the entire theme, specific sections or specific blocks.
Presets
Configurable presets for options to avoid repetition.
Location
The schema should be created at the following location in your local storage disk:
"themes/{$theme}/blueprint/schema.json";
When you have made unsaved changes to the schema a copy will be temporarily made at:
"blueprint/{$theme}/temp/versions/{$version}/schema.json"
And when you save any changes a new schema will be stored at:
"blueprint/{$theme}/versions/{$version}/schema.json"
Where 
$theme is your store's theme and 
$version is the current active version (defaults to 
main).
Templates
Templates define the major page types that your theme supports.
Types
These are the supported template types as of 
10/27/2025:
homepage
listings
products
pages
cart
blogs (if 
aerocargo/blog 
1.x or 
2.x is installed)
blog-listings (if 
aerocargo/blog 
2.x is installed)
error-404
Structure
Key
Description
Required?
id
A unique identifier for the template.
Yes
type
The type of template (e.g. 
homepage, 
products, 
pages).
Yes
variants
An array of variations for this template.
No
variants.*.id
A unique identifier for the template variant.
Yes
variants.*.name
The name of the template variants.
Yes
Example
{
    "templates": {
        "homepage": {
            "id": "homepage",
            "type": "homepage"
        },
        "products": {
            "id": "products",
            "type": "products",
            "variants": [
                {
                    "id": "default",
                    "name": "Default Product"
                }
            ]
        }
    }
}
Sections
Sections are reusable building blocks that can be added to templates.
Structure
Key
Description
Required?
id
A unique alpha-numeric identifier for the section.
Yes
preview
Filename of an image located in public storage at 
/images/blueprint/previews (used in the section picker).
No
icon
The key of an icon to use (overrides the predicted icon determined by what settings the section contains).
No
name
The display name of the section.
Yes
max_blocks
The maximum number of blocks allowed in this section.
No
settings
An array of Setting objects.
No
blocks
An array of Block objects.
No
scopes
An array of Scope objects.
No
variations
An array of Variation objects.
No
Example
{
    "id": "announcement-bar",
    "preview": "announcement-bar.png",
    "name": "Announcement Bar",
    "max_blocks": 4
}
Blocks
Blocks represent repeatable content items within a section.
Structure
Key
Description
Required?
type
The type of block (e.g. 
message, 
image, 
button)
Yes
display
The title of the block (overrides the auto-generated one determined from the block’s settings)
No
name
The name of the block (displayed in the block picker)
Yes
settings
An array of Setting objects
Yes
Example
{
  "type": "message",
  "name": "Message",
  "settings": []
}
Settings
Settings are configurable options for the entire theme, specific sections or specific blocks
Types
These are the supported setting types as of 
10/27/2025:
checkbox
color
css
eloquent
html
image
link
number
pill_select
radio
range
richtext
select
text
video
Structure
Base Setting
Key
Description
Required?
id
A unique identifier for the setting
Yes
type
The setting type (e.g. 
color, 
select, 
checkbox, 
eloquent)
Yes
label
The name of the setting shown in the editor
Yes
default
The default value for this setting
No
group
A group name (e.g. 
custom_styling) to organize related settings
No
info
Additional helper text or hint
No
rules
A rule string that determines when the setting should show/hide
No
Eloquent Setting
Key
Description
Required?
model
The model that the eloquent setting is for, e.g. 
product
Yes
Number Setting
Key
Description
Required?
unit
The unit of the number, e.g. 
mph
No
min
The minimum value the number setting can be
No
max
The maximum value the number setting can be
No
step
The step size used
No
Radio Setting
Key
Description
Required?
preset
An id of an options preset to use
*
options
An array of options
*
options.*.value
The value of the option
Yes
options.*.label
The label for the option
Yes
* One of 
preset and 
options is required, if both are present 
preset will take priority.
Range Setting
Key
Description
Required?
unit
The unit of the number, e.g. 
mph
No
min
The minimum value the number setting can be
No
max
The maximum value the number setting can be
No
step
The step size used
No
Select Setting
Key
Description
Required?
preset
An id of an options preset to use
*
options
An array of options
*
options.*.value
The value of the option
Yes
options.*.label
The label for the option
Yes
* One of 
preset and 
options is required, if both are present 
preset will take priority.
Pill Select Setting
Key
Description
Required?
preset
An id of an options preset to use
*
options
An array of options
*
options.*.value
The value of the option
Yes
options.*.label
The label for the option
Yes
* One of 
preset and 
options is required, if both are present 
preset will take priority.
Examples
[
    {
        "id": "background_color",
        "type": "color",
        "label": "Background colour",
        "default": "#ffffff"
    },
    {
        "id": "border",
        "type": "checkbox",
        "label": "Show separator line",
        "default": true
    },
    {
        "id": "padding_bottom",
        "group": "custom_styling",
        "label": "Padding bottom",
        "type": "select",
        "default": "xxs",
        "options": [
            {
                "label": "None",
                "value": "0"
            },
            {
                "label": "Small",
                "value": "sm"
            },
            {
                "label": "Medium",
                "value": "md"
            },
            {
                "label": "Large",
                "value": "lg"
            }
        ]
    },
    {
        "id": "scoped_css",
        "group": "custom_styling",
        "label": "CSS",
        "type": "css",
        "info": "Add custom styles to this section only."
    },
    {
        "id": "text",
        "type": "richtext",
        "label": "Text",
        "default": "Welcome to our store"
    },
    {
        "id": "link",
        "type": "link",
        "label": "Link"
    }
]
Scopes
Scopes are used in sections to define which configs/templates they are available for use in.
Structure
Key
Description
Required?
id
The config or template that the scope applies for
Yes
allowed
If the section is allowed or not in that config/template
Yes
Example
[
    {
        "id": "header",
        "allowed": true
    }
]
A section which the above scope will only be available for use inside the 
header config.
Presets
Presets are configurable options to avoid repetition.
Structure
Key
Description
Required?
options
An array of options
No
options.*.value
The value of the option
Yes
options.*.label
The label for the option
Yes
Example
{
    "options": {
        "padding": [
            {
                "label": "None",
                "value": "0"
            },
            {
                "label": "Extra extra small",
                "value": "xxs"
            },
            {
                "label": "Extra small",
                "value": "xs"
            },
            {
                "label": "Small",
                "value": "sm"
            },
            {
                "label": "Medium",
                "value": "md"
            },
            {
                "label": "Large",
                "value": "lg"
            },
            {
                "label": "Extra large",
                "value": "xl"
            }
        ]
    }
}
Adding this preset to a setting will allow it to inherit these options without having to explicitly define them on it.
Variations
Variations are used in sections to define layout presets for blocks.
Structure
Key
Description
Required?
id
A unique identifier for the variation
Yes
name
The name of the variation
Yes
blocks
An array of Block objects
Yes
Example
{
    "id": "cms-grid",
    "name": "Content Grid",
    "settings": [],
    "blocks": [
        {
            "type": "image",
            "name": "Image",
            "settings": []
        },
        {
            "type": "text",
            "name": "Text",
            "settings": []
        }
    ],
    "variations": [
        {
            "id": "image-text",
            "name": "Image (Left), Text (Right)",
            "blocks": [
                {
                    "type": "image"
                },
                {
                    "type": "text"
                }
            ]
        },
        {
            "id": "text-image",
            "name": "Text (Left), Image (Right)",
            "blocks": [
                {
                    "type": "text"
                },
                {
                    "type": "image"
                }
            ]
        }
    ]
}

How do I change where the schema is loaded from?
Fallback Schema Location
The default fallback schema location is: 
themes/{$theme}/blueprint/schema.json. It is the base version of the schema, one that has had no changes made via the editor.
setFallbackSchemaLoader allows you to change the location that the fallback version of the schema is located at.
For example:
\Aero\Blueprint\Facades\SchemaRepository::setFallbackSchemaLoader(function () {
    $path = base_path("modules/aerocargo/acme/schema.json");
    if (file_exists($path)) {
        return json_decode(file_get_contents($path), true);
    }
    return [];
});
Temp Schema Location
The default temp schema location is: 
blueprint/{$theme}/temp/versions/{$version}/schema.json. It is the version of the schema that is temporarily saved while changes are pending via the editor.
setTempSchemaLoader allows you to change the location that the temp versions of schemas are located at.
For example:
\Aero\Blueprint\Facades\SchemaRepository::setTempSchemaLoader(function (string $version) {
    $path = base_path("modules/aerocargo/acme/temp/versions/{$version}/schema.json");
    if (file_exists($path)) {
        return json_decode(file_get_contents($path), true);
    }
    return [];
});
Active Schema Location
The default active schema location is: 
blueprint/{$theme}/versions/{$version}/schema.json. It is the version of the schema currently active for the theme.
setActiveSchemaLoader allows you to change the location that the active versions of schemas are located at.
For example:
\Aero\Blueprint\Facades\SchemaRepository::setActiveSchemaLoader(function (string $version) {
    $path = base_path("modules/aerocargo/acme/versions/{$version}/schema.json");
    if (file_exists($path)) {
        return json_decode(file_get_contents($path), true);
    }
    return [];
});
If you move the location that the active schema is loaded from, you will likely need to also use 
setActiveSchemaPathResolver and 
setSaveSchemaHandler to handle saving the schema appropriately.
Or perhaps, you'd like to load the fallback schema as the active schema with only the templates from the actual active schema merged in:
\Aero\Blueprint\Facades\SchemaRepository::setActiveSchemaLoader(function (string $version, string $disk, string $path) {
    // This is the one from storage that is currently active
    $activeSchema = json_decode(Storage::disk($disk)->get($path), true) ?? [];
    // This is the preset schema (the one from the theme)
    $fallbackSchema = \Aero\Blueprint\Facades\SchemaRepository::getFallbackSchema();
    // Merge only the templates from the active schema into the fallback schema
    return array_merge($fallbackSchema, [
        'templates' => $activeSchema['templates'] ?? $fallbackSchema['templates'] ?? [],
    ]);
});
Saving Active Schema to Custom Location
setActiveSchemaPathResolver allows you to change the path that the active schema is considered to be located, it should be used in conjunction with 
setActiveSchemaLoader so that functionality such as saving collision checks still work.
For example:
\Aero\Blueprint\Facades\SchemaRepository::setActiveSchemaPathResolver(function (string $version) {
    return base_path("modules/aerocargo/acme/versions/{$version}/schema.json");
});
setSaveSchemaHandler allows you to change how the schema is saved, it should be used in conjunction with 
setActiveSchemaLoader so that the schema is saved correctly to the new location.
\Aero\Blueprint\Facades\SchemaRepository::setSaveSchemaHandler(function (string $version, array $schema) {
    \Illuminate\Support\Facades\File::put(
        base_path("modules/aerocargo/acme/versions/{$version}/schema.json"),
        json_encode($schema, JSON_PRETTY_PRINT)
    );
});

Configs

What is a config?
A config stores a JSON representation of the page layout created via the theme editor.
Location
Configs should be created at the following location in your local storage disk:
"themes/{$theme}/blueprint/presets/config/{$key}.json"
When you have made unsaved changes to the config a copy will be temporarily made at:
"blueprint/{$theme}/temp/versions/{$previewVersion}/config/{$key}.json"
And when you save any changes a new config will be stored at:
"blueprint/{$theme}/versions/{$version}/config/{$key}.json"
Where 
$theme is your store's theme, 
$key is the configs name, 
$version is the current active version (defaults to 
main) and 
$previewVersion is the current preview version (auto-generated).
Example
{
    "containers": [
        {
            "id": "container__6ca06df5184f4189b8e741baf8a07857",
            "columns": [
                {
                    "id": "column__e226403543f44bb4ae2e692ba02acc58",
                    "sections": [
                        {
                            "id": "section__announcement-bar__f79ee129ad1f4df49dd0b9532a74d7bd",
                            "key": "announcement-bar",
                            "blocks": [
                                {
                                    "id": "block__message__82eb8b4a2e524a4fb7ab0e69a6c1c39f",
                                    "type": "message"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}