Custom Schemas — Total CMS 3

Available in Pro. Lite and Standard licences can use the built-in schemas but cannot create or edit custom ones. A custom schema is a JSON file in tcms-data/.schemas/ that defines a business object of your own — a team member, a product, a case study — and everything downstream is generated from it: the admin editing form, the collection list, save-time validation, the REST surface and what an AI agent sees over MCP.

The shape is small. id names the schema, description explains its purpose in the admin, and category groups it in the sidebar. properties is the substance — each key is a property with a field (how it is edited), a type (how it is stored), a label and any validation rules. required lists the properties an object cannot be saved without, enforced server-side on every save whether it came from the form, the API, the CLI or an import.

index is the setting people underestimate. It names the properties copied into the collection's index, which is what listing, filtering and sorting read without opening every object file. It is also the lever for queryability: a property that is not indexed cannot be filtered or sorted, in the admin, in Twig, in the REST API or over MCP. Adding a property to index is how you make it queryable — nothing else does. formgrid arranges the fields in the admin form using a CSS-Grid-style block of property names, so a long form can be laid out in the shape the editor actually thinks in.

inheritFrom shares properties across schemas without duplicating them. A base-content schema holding title, author and date can be the parent of every editorial type on the site; the child's own definitions win on any name collision, parent properties are merged in, and both the required and index arrays are combined with duplicates removed. Multiple parents are supported, inheritance is one level deep, missing parents are skipped silently, and a schema other schemas inherit from cannot be deleted.

A concrete case: an article schema inherits title, author and date from base-content, adds a styled-text content and a category select, requires id and content, and indexes id and category. The resolved schema carries all five properties with merged required and index lists — and the moment it is saved, the admin has a form for it and the API and MCP describe it accurately.

What you get

The form follows the schema

Each property's field type decides its editor. Add a property and the admin form gains the right control with no interface work.

index is the query lever

Only indexed properties can be filtered or sorted — in the admin, in Twig, over REST and over MCP. Adding a property to index is what makes it queryable.

Inheritance without duplication

inheritFrom pulls a parent's properties in and merges its required and index arrays. Child definitions win on any collision.

Lay the form out

formgrid arranges fields in a CSS-Grid-style block of property names, so a long form reads the way an editor works rather than top to bottom.

Validation on every path

The required array is a hard data invariant, enforced server-side whether the save came from the admin form, the API, the CLI or an import.

In practice

One snippet

{% set inherited = cms.schema.inheritedProperties('article') %}
{% for prop in inherited %}
	<p>{{ prop.field }} ({{ prop.type }}) — from {{ prop.source }}</p>
{% endfor %}

Twig can read a schema's resolved shape, including which parent each inherited property came from.

FAQ

Common questions

Which edition do I need?

Pro. Lite and Standard can use the built-in schemas but cannot create or edit custom ones. Data on a site that downgrades from Pro still renders — the schema editor is locked, not the content.

Where do custom schemas live?

As JSON files in tcms-data/.schemas/, in the standard JSON Schema format. They can be edited in the admin, through the API, over MCP, or in your editor.

Can I extend a schema that ships with Total CMS?

Yes, with inheritFrom. A custom schema that inherits from a reserved one keeps the properties core expects and adds your own on top.

Why can't I filter on a property I just added?

It is almost certainly not in the schema's index array. Filtering and sorting read the collection index, so a property has to be indexed before any surface can query it.

Related features

Want the details? Read the Custom schemas documentation →

Or keep browsing: every Total CMS feature →

Start Your Free 45-Day Trial

Model your content, not someone else's