# 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`](https://agora.aerocommerce.com/packages/aerocargo/blog) `1.x` or `2.x` is installed)
- `blog-listings` (if [`aerocargo/blog`](https://agora.aerocommerce.com/packages/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
```json
{
"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
```json
{
"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](https://github.com/aerocommerce/blueprint#schema--settings) objects | Yes |
### Example
```json
{
"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
```json
[
{
"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
```json
[
{
"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
```json
{
"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
```json
{
"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:
```php
\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:
```php
\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:
```php
\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:
```php
\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:
```php
\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.
```php
\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
```json
{
"containers": [
{
"id": "container__6ca06df5184f4189b8e741baf8a07857",
"columns": [
{
"id": "column__e226403543f44bb4ae2e692ba02acc58",
"sections": [
{
"id": "section__announcement-bar__f79ee129ad1f4df49dd0b9532a74d7bd",
"key": "announcement-bar",
"blocks": [
{
"id": "block__message__82eb8b4a2e524a4fb7ab0e69a6c1c39f",
"type": "message"
}
]
}
]
}
]
}
]
}
```