Extension Schemas Since 3.3.0

Extensions can provide collection schemas in two ways: read-only schemas that live inside the extension, and installable schemas that are copied into the user’s data directory.

Both approaches require Pro edition or higher.

Read-Only Schemas

Place JSON schema files in a schemas/ directory inside your extension. These schemas are automatically discovered and available throughout Total CMS.

acme/seo-pro/
    extension.json
    Extension.php
    schemas/
        seo-metadata.json

schemas/seo-metadata.json:

{
    "id": "seo-metadata",
    "description": "SEO metadata for pages",
    "category": "seo",
    "properties": {
        "title": {
            "type": "text",
            "label": "SEO Title",
            "maxLength": 60
        },
        "description": {
            "type": "text",
            "label": "Meta Description",
            "maxLength": 160
        },
        "canonical": {
            "type": "url",
            "label": "Canonical URL"
        }
    },
    "required": ["id", "title"],
    "index": ["id", "title"]
}

Read-only schemas:

• Are managed by the extension and stay in sync with extension updates
• Cannot be edited by the user through the admin UI
• Are removed when the extension is disabled or removed
• Appear in the schema list alongside built-in and custom schemas

Lookup Priority

When Total CMS looks up a schema, it checks in this order:

1. Built-in schemas (in resources/schemas/)
2. Extension schemas (in extension schemas/ directories)
3. Custom schemas (in tcms-data/.schemas/)

This means an extension schema cannot override a built-in schema, and a custom schema can override an extension schema if needed.

Installable Schemas

For schemas the user should be able to customize after installation, use installSchema() in the boot() method:

public function boot(ExtensionContext $context): void
{
    $context->installSchema([
        'id' => 'product-reviews',
        'description' => 'Customer product reviews',
        'category' => 'commerce',
        'properties' => [
            'rating' => [
                'type' => 'number',
                'label' => 'Rating',
                'min' => 1,
                'max' => 5,
            ],
            'review' => [
                'type' => 'styledtext',
                'label' => 'Review',
            ],
            'author' => [
                'type' => 'text',
                'label' => 'Author Name',
            ],
        ],
        'required' => ['id', 'rating', 'review'],
        'index' => ['id', 'rating'],
    ]);
}

Installable schemas:

• Are copied into tcms-data/.schemas/ on first boot
• Are skipped if a schema with the same ID already exists (no overwrites)
• Become user-owned after installation — the user can edit them freely
• Persist after the extension is removed (the data belongs to the user)

When to Use Which

Approach	Use When
Read-only (schemas/ directory)	The schema is integral to the extension and must stay in sync with it
Installable (installSchema())	The schema is a starting point the user should customize

Most extensions should use read-only schemas. Use installable schemas only when you explicitly want the user to take ownership.