` and is visible in Strapi in the Content-Type Builder. |
| `meta` | object | Fields managed by Strapi or the sync middleware (see below). |
| `fields` | array | The actual content fields, each as `{ name, type, value }`. |
This envelope is identical for all input masks and documents. That also holds when fields are renamed, added, or deleted. Only the entries inside `fields` change as a result.
### Administrative data and SEO fields in meta
`meta` contains the administrative fields of a document. They are deliberately kept separate from the content fields in `fields`:
| **Field** | **Type** | **Note** |
| ------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | number | Internal numeric ID (per language version). |
| `documentId` | string | Stable, cross-language document ID. Determines the file name by default. |
| `locale` | string | Language of this file, for example `de`. The language code does not necessarily match the directory name in the shop (for example `Deutsch`); the mapping is determined by the subshop configuration. |
| `createdAt` / `updatedAt` | string (ISO-8601) | Timestamps from Strapi. |
| `publishedAt` | string or null | `null` for drafts. |
If the Meta-Info plugin is active for a document (see [SEO meta data for CMS pages](/en/strapi-cms/grundlagen-architektur-von-strapi#seo-meta-daten-fur-cms-seiten-meta-info-plugin)), `meta` additionally contains the SEO fields of the page:
| **Field** | **Type** | **Note** |
| ----------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url` | string | SEO URL of the page. |
| `metaTitle` | string | Meta title. |
| `metaDescription` | string | Meta description. |
| `robots` | string\[] | An array, not a comma-separated string. For example `["noindex", "nofollow"]`. |
| `hreflang` | array | References to the language equivalents of the same page, for the hreflang entries in the HTML head. Calculated automatically as soon as the Meta-Info plugin is active. Contains one entry per subshop that serves this language (`{ language, url, subshopId, default }`). |
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
"meta": {
"id": 99,
"documentId": "l9h00uvgblpjvlqqv1va9s44",
"locale": "de",
"createdAt": "…", "updatedAt": "…", "publishedAt": "…",
"url": "agb",
"metaTitle": "Terms and conditions",
"metaDescription": "General terms and conditions",
"robots": ["noindex", "nofollow"],
"hreflang": [
{ "language": "de", "url": "agb", "subshopId": "deutsch", "default": true }
]
}
```
An input mask itself can have content fields with names such as `url` or `robots`. These then appear as regular entries in `fields` and are something **different** from `meta.url` or `meta.robots` (same name, but different meaning and in some cases a different form). SEO values from the Meta-Info plugin always sit in `meta` and never in `fields`. Do not confuse the two when processing them.
### The content fields in fields
`fields` is a list of all input fields of the document. Each entry has exactly three keys:
| **Key** | **Type** | **Meaning** |
| ------- | ----------------- | ---------------------------------------------------------------------------------------------------- |
| `name` | string | The technical field name, as it is currently called in the input mask (may change through renaming). |
| `type` | string | The Strapi field type (see [Field types](#the-field-types)). |
| `value` | depends on `type` | The value. Its form depends on the type. |
Two orderings need to be distinguished:
* **Order of the `fields` list**: it follows the schema definition and is irrelevant for rendering. Therefore, always access fields via `name` and never via position.
* The **order within an array value** (content blocks, repeatable components, relation lists) is layout-critical. It exactly matches the editor's arrangement and must be preserved when rendering.
### The field types
**Scalar types**: `value` is the value directly.
| **type** | **value** |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `string` / `text` | string or null |
| `richtext` | string or null (Markdown or already converted HTML, depending on the sync middleware setting) |
| `enumeration` | string or null |
| `boolean` | boolean or null |
| `integer` / `biginteger` / `decimal` / `float` | number or null |
| `date` / `datetime` / `time` / `timestamp` | string or null |
| `uid` | string or null |
| `json` | arbitrary JSON |
| `blocks` | array of Strapi Blocks nodes or HTML string, depending on the sync middleware setting |
Whether `richtext` and `blocks` values arrive as raw data (Markdown or Blocks JSON) or as finished HTML is a deployment setting of the sync middleware. Clarify with WEBSALE which variant is active for your shop before you adjust the template.
#### Media in the schema format
**`media`**: `value` is a normalized media object with fixed keys (`url`, `alt`, `caption`, `name`, `mime`, `ext`, `width`, `height`, `size`, `formats`). Strapi internals such as IDs, hashes, provider data, and timestamps are deliberately removed so that Strapi-internal changes do not reach the shop. If a value is missing, it is `null`. For multi-media, `value` is an array of such objects.
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"name": "logo",
"type": "media",
"value": {
"url": "/uploads/websale_logo_576a45762c.webp",
"alt": "Websale company logo",
"caption": null,
"name": "websale_logo.webp",
"mime": "image/webp",
"ext": ".webp",
"width": 500,
"height": 75,
"size": 4.26,
"formats": {
"thumbnail": { "url": "/uploads/thumbnail_…", "width": 245, "height": 37, "mime": "image/webp", "size": 3.07 }
}
}
}
```
#### Components and relations
**`component`**: `value` contains its own `fields` list. For repeatable components, `value` is an array of such objects.
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"name": "button",
"type": "component",
"value": {
"fields": [
{ "name": "label", "type": "string", "value": "More" },
{ "name": "link", "type": "string", "value": "/info" }
]
}
}
```
**`dynamiczone`** (content blocks): `value` is an array of blocks. Each block carries its component name in `component`, its `id`, and its own `fields` list.
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"name": "content",
"type": "dynamiczone",
"value": [
{
"component": "elemente.ws-markup",
"id": 96,
"fields": [
{ "name": "Markup", "type": "richtext", "value": "Terms content" },
{ "name": "FullWidth", "type": "boolean", "value": false }
]
}
]
}
```
**`relation`**: `value` contains the linked documents, recursively with their own `fields` list. A single relation returns an object, a multi-relation an array. The resolution depth is limited. Deeper relations that are no longer loaded appear as `value: null`. Self-referencing relations (for example nested navigations) are additionally cut off by a cycle protection. The same type is only resolved once per path.
Keep the load depth in mind in the template as well: `$wsExternalData.load` truncates deeply nested structures via the `maxDepth` option. In the examples on this page, `maxDepth: 20` is used. See [\$wsExternalData](/en/frontend/referenz/module/wsexternaldata).
### Stability guarantee and its limit
**The structure is stable:** No matter what happens to the input masks, every file is `{ contentType, meta, fields[] }` and every field is `{ name, type, value }`. Templates can rely on that 100%.
**The meaning is not stable:** If an editor renames a field `title` to `titel`, that comes through cleanly. But in `name`, it now reads `titel`. A template that specifically searches for `title` no longer finds anything and outputs nothing at that place. The mapping of field names to their meaning is an agreement between editors and template owners. The format cannot enforce it. The only exception are the SEO fields: through the Meta-Info plugin, they always sit at the same place in `meta` in the schema format, regardless of how the input masks are structured.
## Changes compared to the old structure
The following overview compares the new structure with the old data structure of the previous content sync. It is the basis for the template adjustment in the next section. The "New structure" column shows the schema format. The changes to the input-mask identifier, the component identifier, the media, `localizations`, and the file names apply to **both** formats. For the SEO fields, only the storage in the schema format (`meta`) is confirmed; for the mapping format, it is still open.
| **Aspect** | **Old structure** | **New structure (schema)** |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Envelope | `{ "id", "attributes": { …all fields… }, "content_type" }`
The fields sit inside an `attributes` wrapper. | `{ contentType, meta, fields[] }`
There is no more `attributes` wrapper. |
| Input-mask identifier | short slug, for example `"contentpage"` | full Strapi UID, for example `"api::contentpage.contentpage"` |
| Component identifier | `"__component"` | `"component"` (on the individual content blocks) |
| Media | REST wrapper `{ "data": { "id", "attributes": { … } } }` including Strapi internals | flat, normalized media object with a fixed set of keys (see above) |
| SEO fields | dedicated content component (for example "Meta Information" with `MetaTitle`, `MetaDescription`, `SeoURL`, `MetaRobots`), maintained editorially in the input mask | no longer a content field. The values sit in `meta` via the Meta-Info plugin with new names: `SeoURL` → `url`, `MetaTitle` → `metaTitle`, `MetaDescription` → `metaDescription`, `MetaRobots` → `robots` (now an **array** instead of a string). Newly added: `hreflang`. |
| `localizations` | always present, even if empty | completely removed |
| File name | derived from content and descriptive, for example `tpl_about.json` | by default based on `documentId`, for example `l9h00uvgblpjvlqqv1va9s44.json` |
The switch of file names to `documentId` affects every place in the template that loads a JSON file via a descriptive name. The `documentId` is the central, stable identity of a document. The numeric `id` is not suitable for that because it changes per language version.
## Migrating templates: the eight steps
Three notes up front:
1. **The code examples are patterns to transfer, not code to be copied unchanged.** The "after" code **replaces** the corresponding existing location in your template – but inside the test-mode switch from step 2, so that the previous code initially remains in place for the live output.
2. **The "before" examples show a typical pattern of the old structure.** Because the old structure was set up differently per shop, the actual locations in your shop may differ.
3. **Work behind the test-mode switch from the start** (step 2). Otherwise you change the live output before you have verified it.
The examples use the schema format throughout because it involves the larger rework. Where the mapping format differs, this is noted in the respective step.
**Prerequisite:** The new files must already be generated for your shop, otherwise the test mode has nothing to work with. Check in the JSON directory whether there are files with `documentId` names (`.json` and `.schema.json`). The old files with descriptive names remain alongside them during the transition phase. Activation and regeneration are initiated by WEBSALE.
### Step 1: Find the affected locations
**When needed:** Always.
Search the template repository (GitLab) for all places where Strapi JSON is loaded or read:
* `$wsExternalData.load(` – loads a single file. Relevant are the calls with the option `source: "system"` and a path that points to the JSON directory.
* `$wsExternalData.read(` – reads a directory and returns a list of file names.
* the subsequent field accesses on the loaded data, typically recognizable by `attributes` and `__component`.
The result is a list of the templates that will be adjusted in the following steps. For each hit, note which Strapi document is loaded there – you will need the "file ↔ document" mapping in step 3.
### Step 2: Add a test-mode switch
**When needed:** Always, and specifically **before** the first content change.
No second Strapi instance is needed for the check. Because the old files remain in place during the transition phase, old and new files sit side by side in the JSON directory. You can therefore switch between old and new in the same template: in [test mode](/en/frontend/referenz/module/wstestmode), the template loads and renders the new files, while the live output continues to work unchanged with the old ones. This keeps the migration safe at all times. The live page remains untouched until step 8.
The switch covers not just the load call but the entire output block\*\*.\*\* The field accesses of the new structure (steps 4 to 7) do not fit the old files. If you only switched the file name, the live output would immediately be empty.
**Before (old structure, without a switch):**
```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $cCMSLoadOptions = {"source": "system", "type": "json", "maxDepth": 20} }}
{{ var $cCMSFile = ["json/Deutsch/tpl_about.json"] | join }}
{{ var $cCMSData = $wsExternalData.load($cCMSFile, $cCMSLoadOptions) }}
{{# … previous output code … #}}
```
**After (with a switch – scaffolding that you fill in steps 3 to 7):**
```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $cCMSLoadOptions = {"source": "system", "type": "json", "maxDepth": 20} }}
{{ if $wsTestMode.active }}
{{# Test mode: new structure #}}
{{ var $cCMSFile = ["json/Deutsch/l9h00uvgblpjvlqqv1va9s44.schema.json"] | join }}
{{ var $cCMSData = $wsExternalData.load($cCMSFile, $cCMSLoadOptions) }}
{{# … new output code from steps 4 to 7 … #}}
{{ else }}
{{# Live: previous structure, unchanged #}}
{{ var $cCMSFile = ["json/Deutsch/tpl_about.json"] | join }}
{{ var $cCMSData = $wsExternalData.load($cCMSFile, $cCMSLoadOptions) }}
{{# … previous output code … #}}
{{ /if }}
```
All following steps work exclusively in the upper branch. How to invoke test mode in the shop is described under [Switching shop test modes on/off](/en/testmodi-des-shops-ein-ausschalten).
In larger templates, a switch per output location becomes hard to read. In that case, it is more practical to leave the old output template unchanged and maintain the new version as a dedicated file that is only included in test mode. The procedure is described under [Adapting templates for Strapi content](/en/strapi-cms/templates-fur-strapi-inhalte-anpassen).
### Step 3: Adjust the file names in the load calls
**When needed:** Always.
**The path stays, only the file name changes.** The JSON files remain in the same directory as before: in the JSON directory of your shop, which the templates reach via the option `source: "system"` – for example `json/Deutsch/` for the German-language content. Both new formats sit there **side by side**, in the same directory as the old file did before.
Instead of a descriptive name, each file carries the `documentId` of the document by default:
| | **Before** | **After** |
| -------------- | ----------------------------- | --------------------------------------------------- |
| mapping format | `json/Deutsch/tpl_about.json` | `json/Deutsch/l9h00uvgblpjvlqqv1va9s44.json` |
| schema format | (did not exist) | `json/Deutsch/l9h00uvgblpjvlqqv1va9s44.schema.json` |
**How to find the `documentId`:** Open the document in Strapi in the Content Manager. The `documentId` then appears in the browser's address bar. In addition, it is present in every generated file of the schema format under `meta.documentId`.
*Screenshot: Content Manager with an opened document, `documentId` highlighted in the address bar.*
**Where to adjust:**
* In every `$wsExternalData.load(...)` call that loads a Strapi file by its name – in the scaffolding from step 2, that is the value of `$cCMSFile` in the test-mode branch.
* **Not** in `$wsExternalData.read(...)` calls. These read a directory and remain unchanged. If your template further evaluates the read file names by content – for example, to derive the appropriate page from the name –, that logic must also be adjusted, because the names are no longer descriptive.
The most commonly overlooked point: mapping files and self-built naming conventions. If your template assembles the file name only at runtime (for example from the called URL via its own mapping file), this mapping must be switched to `documentId` file names.
### Step 4: Update field accesses
**When needed:** Always. The scope differs depending on the format.
This refers to the place that reads the value of an input field from the loaded data – for example the page title.
**In the mapping format**, only the `attributes` wrapper is removed. `$cCMSData.attributes.title` becomes `$cCMSData.title`. Nothing more needs to be done on the field accesses.
**In the schema format**, the values are no longer directly under their field name but as entries in the `fields` list. Convert this list once into a name/value object. Afterwards you access it via the field name as usual:
The load call from step 2 remains unchanged. Only the output part below it is replaced:
**Before (old structure):**
```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{= $cCMSData.attributes.title }}
```
**After (schema format):**
```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $cCMSData }}
{{# convert the fields list once into a name/value object #}}
{{ var $cFields = {} }}
{{ foreach $cField in $cCMSData.fields }}
{{ $cFields[$cField.name] = $cField.value }}
{{ /foreach }}
{{= $cFields.title }}
{{ /if }}
```
The check `{{ if $cCMSData }}` is not decorative: `$wsExternalData.load` returns `null` if the file is missing or invalid. Without this check, the page stays empty without any indication.
This pattern works identically at every level: for the document fields, inside components (`value.fields`), and for the blocks of the content blocks (see next step).
### Step 5: Adjust content blocks (dynamic zone)
**When needed:** If your template renders the content blocks of a page. That applies to practically every content page with freely combinable components.
Two things change:
* The component identifier is now called `component` instead of `__component` – that applies to **both** formats.
* In the schema format, the field values of a block sit in its own `fields` list.
Replace the existing render code according to this pattern:
**Before (old structure):**
```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ foreach $cItem in $cCMSData.attributes.content }}
{{ if $cItem.__component == "elemente.ws-markup" }}
{{! $cItem.Markup }}
{{ /if }}
{{ /foreach }}
```
**After (mapping format):**
```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ foreach $cItem in $cCMSData.content }}
{{ if $cItem.component == "elemente.ws-markup" }}
{{! $cItem.Markup }}
{{ /if }}
{{ /foreach }}
```
**After (schema format, `$cFields` from step 4):**
```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ foreach $cItem in $cFields.content }}
{{ var $cItemFields = {} }}
{{ foreach $cField in $cItem.fields }}
{{ $cItemFields[$cField.name] = $cField.value }}
{{ /foreach }}
{{ if $cItem.component == "elemente.ws-markup" }}
{{! $cItemFields.Markup }}
{{ else }}
{{# component not implemented: make visible in test mode #}}
{{ if $wsTestMode.active }}
{{ /if }}
{{ /if }}
{{ /foreach }}
```
Replace the component names and fields in the example with those of your shop. The order of the blocks matches the editor's arrangement and is output unchanged.
Keep a `{{ else }}` branch for unknown components, or add one. Otherwise a newly created block disappears silently from the page instead of standing out.
### Step 6: Adjust media accesses
**When needed:** Everywhere images or files from Strapi are output. Applies to both formats.
The `data`/`attributes` wrapper around media is removed. Image URL, alt text, and responsive formats sit directly in the normalized media object. Additionally, the alt text is now called `alt` instead of `alternativeText`. Replace the existing image outputs according to this pattern:
**Before (old structure):**
```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
```
**After (schema format, `$cFields` from step 4):**
```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
```
**After (mapping format):**
```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
```
Newly available directly are also `width`, `height`, and the responsive variants under `formats`, for example `$cFields.logo.formats.thumbnail.url`. Only output these values if they are populated: missing entries are `null`, and not the same formats are generated for every shop.
### Step 7: Read SEO fields from `meta`
**When needed:** If your template outputs meta title, meta description, robots, or the SEO URL from the Strapi data. The examples show the schema format (for the mapping format, see the note under [What to watch out for with the mapping format](#what-to-watch-out-for-with-the-mapping-format)).
These values previously came from a content component (for example "Meta Information") and in the future sit in the `meta` section of the file, with new field names (see [comparison](#changes-compared-to-the-old-structure)). Replace the existing accesses according to this pattern:
**Before (old structure):**
```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{= $cCMSData.attributes.MetaInformation.MetaTitle }}
```
**After (schema format):**
```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{= $cCMSData.meta.metaTitle }}
```
Two points stand out here in particular:
* **`robots` is now an array** and must be joined into a string for output in the meta tag. `join` is called as a function with a separator for that; the filter notation `| join` in the path examples on this page joins without a separator.
* **The SEO fields sit in `meta`, not in `fields`.** The name/value object `$cFields` from step 4 does not contain them.
Newly available is also `meta.hreflang` with one entry per subshop that serves this language. If you want to output hreflang tags, that is the data source for it.
### Step 8: Verify in test mode and go live
**When needed:** Always, as the last step.
Open the shop in test mode (see [Switching shop test modes on/off](/en/testmodi-des-shops-ein-ausschalten)) and check every migrated page.
*Screenshot: shop in test mode showing a migrated content page.*
Checklist:
* Are all content blocks output – and in the order the editor set in Strapi?
* Do all images appear including the responsive formats, with alt texts?
* Is the SEO output in the HTML head correct: meta title, meta description, robots?
* Are the pages reachable via their SEO URLs?
* Are there empty places where content used to be? That is the typical hint at a field name that no longer matches.
It is best to compare test-mode and live output of the same page directly side by side.
Only when all pages have been checked, remove the switch from step 2: the test-mode branch becomes the regular code, and the `{{ else }}` branch with the old load call and old output is removed.
## When something does not work
| **Symptom** | **Likely cause** | **Check** |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The page stays completely empty, no content from Strapi | The file was not found or not loaded. `$wsExternalData.load` returns `null` in that case. | Check file name and `documentId` (step 3). For the error cause, `$wsExternalData.getLastError()` provides a code, see [\$wsExternalData](/en/frontend/referenz/module/wsexternaldata). |
| Individual values are missing, the rest of the page is there | The field name in the template no longer matches the field name in Strapi. | In the schema format, compare the `name` values in `fields` with the field names in the template. |
| A content block is not output | The component identifier is still checked via `__component`, or the component is not implemented in the template. | Step 5, especially the `{{ else }}` branch for unknown components. |
| Images are missing or have no alt text | The old `data`/`attributes` wrapper or `alternativeText` is still being used. | Step 6. |
| Robots tag contains something like `noindexnofollow` | The `meta.robots` array was joined without a separator. | Step 7. |
| Deeply nested content is truncated | `maxDepth` in the load call is too small, or a relation was no longer resolved by the sync middleware (`value: null`). | Load options and section [Components and relations](#components-and-relations). |
For the switch date of your shop as well as the activation of the formats and the regeneration of the files for existing content (backfill), contact your WEBSALE contact.
## Related topics
- [Migration](/en/migration.md)
- [Template migration](/en/migration/migration-websale-v8s-neue-version/template-migration.md)
- [Data migration](/en/migration/daten-migration.md)
- [Migration WEBSALE V8s -> new version](/en/migration/migration-websale-v8s-neue-version.md)
- [Configuration migration](/en/migration/migration-websale-v8s-neue-version/konfiguration-migration.md)