Export and import of a layout
What it does
A page can be written to a file and read back: into another page, on another site, or by a script. The file is JSON, has a JSON Schema, and names what it uses by UUID, so it does not depend on the ids of one site. Core's content export (content:export, the content folder of a recipe) works too and is described in Architecture; the file here is for moving a layout, with a check on the way in.
Limitations
- Only the files of media items are carried, and only on request. Other files (a file field of a paragraph) are described in
references.file, not in the file. - Image style derivatives and thumbnails are not carried: the site makes them again.
- Paragraphs: fields of text, numbers, links and references to other content by UUID are carried; paragraphs in a translation are named, not included. Presets and templates are
includesof their own. - A block of the library that exists on the site is used as it is there, even when the file has another version of it.
The file
{
"$schema": "https://example.org/frame-editor/schema/layout.json",
"format": "frame-layout",
"formatVersion": 1,
"exported": {
"site": "Example",
"at": "2026-11-13T18:00:00+00:00",
"entity": "node",
"bundle": "landing_page",
"uuid": "3f6c1c8e-0f6a-4a3a-9a53-0c9d3a8f5b21",
"title": "Summer sale",
"langcode": "en"
},
"components": { "frame:button": 1, "frame:heading": 1, "frame:image": 1 },
"layout": {
"root": { "props": [] },
"content": [
{ "type": "frame:heading", "version": 1, "props": { "id": "h1", "text": "Summer sale", "level": "h1" } },
{ "type": "frame:image", "version": 1, "props": { "id": "i1", "image": { "media_uuid": "5b6774af-05f2-4405-9987-30b24ef9f7e9", "style": "style:large" } } },
{ "type": "frame:button", "version": 1, "props": { "id": "b1", "label": "Shop", "url": "entity:node/a0309e08-2910-481e-977b-8028709b399c" } },
{ "type": "field:body", "version": 1, "props": { "id": "f1" } },
{ "type": "frame_saved:0d1d2d5c-6fd3-4b0c-9b4b-2c5c9d0b6f10", "version": 1, "props": { "id": "l1" } }
],
"version": 2
},
"translations": {
"de": { "strings": { "h1.text": "Sommerschlussverkauf" }, "versions": { "h1": 1 } }
},
"includes": {
"saved": [
{ "uuid": "0d1d2d5c-6fd3-4b0c-9b4b-2c5c9d0b6f10", "label": "Newsletter strip", "layout": { "content": [ … ] } }
],
"presets": [
{ "uuid": "7c1f…", "label": "Big title", "description": "", "locked": ["level"], "default": false,
"layout": { "content": [ { "type": "frame:heading", "version": 1, "props": { "id": "preset", "level": "h2", "size": "xl" } } ] } }
],
"paragraphs": [
{ "uuid": "…", "type": "text_block", "fields": { "field_text": [ { "value": "…" } ] } }
],
"media": {
"5b6774af-05f2-4405-9987-30b24ef9f7e9": {
"bundle": "image", "name": "Red square", "langcode": "en", "status": true,
"fields": { "field_caption": [ { "value": "A red square" } ] },
"files": [
{ "field": "field_media_image", "uuid": "9c1f…", "filename": "red.png", "mime": "image/png",
"uri": "public://2026-11/red.png", "size": 1234, "properties": { "alt": "A red square", "width": 360, "height": 240 },
"data": "iVBORw0KGgo…" }
]
}
}
},
"references": {
"media": [ { "uuid": "5b6774af-…", "name": "Red square", "bundle": "image" } ],
"node": [ { "uuid": "a0309e08-…", "title": "Shop", "bundle": "landing_page" } ]
}
}| Key | What it is |
|---|---|
$schema, format, formatVersion | What the file is. The version is the version of this format (1). A reader refuses a newer one. |
exported | Where the file comes from: site, time, entity type and UUID, content type, title, language. Information only. |
components | The components the layout uses, with the version of each. |
layout | The stored layout document. Items keep their props.id. What an item names is given by UUID: media_uuid in an image, entity:node/<uuid> in a link (also in rich text and lists), paragraph_uuid for the paragraph of a Paragraph block, frame_saved:<uuid> or paragraphs_library_item:<uuid> for a block of the library. The types of items have no drupal_ in a file. |
translations | Every translation of the page, by language, also in a file exported from a translation (the original is in layout). A content type with synced translations: the translated texts, "<item id>.<prop>". With independent translations: {"layout": …} for each. Unsaved changes in the editor go into the language they were made in. A selection has the translations of the selected items; a selection made in a translation is in that language and has no translations. |
includes | What the layout uses and the other site may not have: saved (blocks of the library, each with its own layout), presets (see Presets), templates (see Templates), paragraphs (the type and the values of the fields; for an item of the Paragraphs Library also library) and, only when asked for, media (see Media files). Later kinds can be added here; a reader skips what it does not know. A file by reference has no saved, presets, templates and paragraphs. |
references | Description of the media and the pages the layout names, for whoever reads the file (a model, a person). The files of the media are in includes.media, when they were asked for. |
Names of items
A stored layout names the items that are not components with drupal_ in front. A file does not: the names say what the item is, and the file does not depend on how the module stores it.
| Item | In storage | In a file |
|---|---|---|
| a component | <provider>:<name> | the same |
| a field of the page | drupal_field:<field> | field:<field> |
| a view | drupal_view:<view>:<display> | view:<view>:<display> |
| a Drupal block | drupal_block:<plugin id> | block:<plugin id> |
| a Paragraph block | drupal_paragraph:<paragraph type> | paragraph:<paragraph type> |
| a saved block, linked | drupal_saved:<uuid> | frame_saved:<uuid> |
| an item of the Paragraphs Library, linked | drupal_saved:<uuid> | paragraphs_library_item:<uuid> |
The exporter turns the stored names into these and the importer turns them back; storage is not changed. The importer also accepts the old names (drupal_field:body, drupal_saved:<uuid>...), also mixed with the new ones.
The names field, view, block, paragraph, frame_saved and paragraphs_library_item are reserved: before the importer looks for a component it reads an id that starts with one of them (and a colon) as one of the items above. A theme or module with one of these names as its machine name cannot have its components in a file. None is expected, and core's rules for the name of an SDC provider (a module or theme) make a clash unlikely.
Settings of Drupal blocks
The settings of a Drupal block are the configuration of its plugin and go into the file as they are. The exporter does not know what a plugin keeps, so only what is recognised everywhere is mapped: a value entity:node/<id> (or entity:taxonomy_term/<id>, entity:user/<id>) becomes a UUID, as in any prop, and is found again on import; a media item picked as {"media": <id>} is described like other media. Any other id a plugin keeps in its settings (a menu name, a view id, a plain entity id as a number) is left as it is, and it is the plugin's job to find it on the site that imports. The settings of a block that does not exist on the importing site are kept in the layout, and the block shows nothing there. Entity Usage and the references of a layout read the settings the same way, so a node named as entity:node/<id> in them is counted as used.
Presets
A block that follows a preset names it in its props, "_preset": "frame_preset:<uuid>", and has only the values that are its own (and _unlocked, the locked options it changes). The file includes the preset: uuid, label, description, locked (the names of the props it decides), default and layout, a document with one item, the component with its version and the values of the preset; what is in its slots is the starting content. Media in the values are described and, with Include media files, carried like those of the page. The versions of the components the presets use are in components, so older ones are brought up to date on import. A preset a theme ships (Presets a theme ships) is named "_preset": "theme:<name>", is not included (it is in the component), and is dropped with a warning on a site whose theme does not have it.
An import:
- uses the preset the site has with that UUID, as it is;
- makes one the site lacks, with the same UUID, when the user has Manage Frame presets (a preset that is the default of its component in the file does not take the place of the site's own default). It is reported as Added to the presets;
- otherwise does not make anything: the blocks get the values of the preset in the file, with what they have of their own over them, and follow nothing. The result says so (
Calm was inserted with its values: you may not add presets); - reports a preset that is neither on the site nor in the file (a file by reference), and leaves the block as it is.
_unlocked is kept for a user who may override locked options, and dropped for one who may not, with the values it unlocks (the preset's are used).
Templates
A page that started from a template names it in its root, "_template": "<uuid>"; its items are its own and are in the file like any. The file includes the template: uuid, label, description, kind, bundles, status and layout, a document like the page's.
An import:
- names the template the site has with that UUID;
- makes one the site lacks, with the same UUID, when the user has Manage Frame templates;
- otherwise makes nothing, and the page names no template. Its items are imported as they are.
Media files
A file normally names the media it uses (references.media, media_uuid) and the other site needs them. With the option include media files (Export > Export page with media files, ?media=1) the file carries them, in includes.media: each media item the layout uses, by UUID, with its type (bundle), name, language, published state, the values of its fields that hold no file (fields, a reference to other content as target_type and target_uuid) and its files (files: the field, the UUID, the name, the type, the size, what the field keeps with the file such as alt, and the file itself in data, base64). It covers an image picked in a component, a background, media embedded in rich text (<drupal-media>), and the media of saved blocks and paragraphs the file includes (not with by reference, which leaves those out). A media item with no file (a remote video) has its source value in fields and no files. A media item the user may not view is only described.
The files are limited: the option is refused when the media files are together more than the limit, which is Most media files in an exported file, in MB on the Components page of the editor (admin/config/content/frame-editor/components), export_media_limit in frame_editor.settings, 25 by default. The message says how large they are and suggests the export without media files.
On import, for each media item of the file:
- a media item with the same UUID on the site is used as it is, and not changed. Nothing is duplicated, also when the same file is imported again;
- else it is made when the media type exists and the user may create media of it: the files with their UUIDs, then the media item with its UUID, as the user who imports. A file goes where the field says (its scheme,
public://unless the field says otherwise, and its directory); a file of that name is not replaced, the new one is renamed. What the file holds is checked as for an upload: the extension must be one the field allows, an image must be an image; - else it is missing: a warning with the reason (the media type does not exist, you may not create it, the file is not allowed), as for a media item that is only named. It keeps its UUID in the layout.
In the editor
Three buttons in the top bar: Export, Import and Template, each with an icon and a word (on a narrow editor the words hide and the icons stay; every button has a title that says what it does).

| Editor | Export | Import | Template |
|---|---|---|---|
| Page | yes | yes (with the permission) | yes (with the permission Manage Frame templates) |
| Template | yes | yes | no |
| Saved block | yes | yes | no |
| Display | no | no | no |
Export opens a small menu of the ways to export:

- Export page downloads what is in the editor now, saved or not, with the unsaved values of the Paragraph blocks.
- Export page by reference leaves out
includes: the file only names the saved blocks and paragraphs, and the site that imports it needs them. - Export page with media files is the same with the files of the media the page uses in the file (see Media files). It is offered when the Media module is on. When the files are more than the limit, the page is not exported and the message says so.
- Export selection exports the components selected in the Structure panel (or the selected component), each with what is in it, as the layout of the file.
Import opens a dialog (no menu) and Template opens the dialog of Save as template.
- Import asks for a file or pasted text, and whether to replace the page or to insert after the selected component (at the end when nothing is selected). The imported layout is an unsaved change of the page, one step of Undo; saving is the usual save. Inserted items get new ids, so ids never clash. What went wrong is in the messages at the bottom right: a refused file lists its reasons and nothing changes, other problems are warnings.
Import is not offered without the permission Import Frame layouts, nor on a translation that shares its structure with the original page.
In the admin
- Export tab of a page that uses the editor, and of a block of the library: By reference and Include media files, then Download.
- Import tab of such a page: a file or pasted text, replace the layout or add it at the end, a revision log message. The page is saved as a new revision, the way the editor saves it.
- Add content from a file, on Content: a new page of a content type that uses the editor, from a file.
What an import does
- Checks the file. Not a layout file, a newer
formatVersion, no layout: refused. - Checks the components. A component this site does not have, a Paragraph block of an unknown paragraph type, or a component in a newer version than the site's: the import stops, with the list. Nothing is created.
- Brings old versions up to date. An item of an older version of its component goes through the steps of Versions and migrations. An item without a version is taken as current.
- Makes what the layout needs. A block of the library or a paragraph of
includesis created when the site does not have one with that UUID; when it has, it is used and not duplicated. Adding to the library takes the permission Manage the Frame library (for an item of the Paragraphs Library, the permission of that module to create one). Presets are treated the same way (see Presets). Without it a block that the site lacks is not made: its content fromincludesis inserted as a copy, with new ids and the first item remembering the block in_library(as Edit copy here does), and the result says so (copied, and a warning such as "Promo was inserted as a copy: you may not add blocks to the library"). A block the site has is linked as usual: placing it needs only the access to edit the page. A paragraph of a page is made when the page is saved, with the values of the file; one that exists on the site and belongs to another page is copied for this page, as for any paragraph that another page owns. - Makes the media of
includes.mediathat the site does not have (see Media files). - Turns UUIDs into ids of this site. A media item or a page that is not here is a warning with its name from
references; it keeps its UUID in the layout (the image stays empty, the link does not work), and importing again once the content is there gives the ids. - Checks the props against the schemas of the components, as the editor does on save. Problems are warnings.
- Saves the layout by the normal path: a new revision of the page, the paragraphs of the page saved with it. Translations in the file go to the translations the page has, in the same mode; the others are reported.
HTTP
Both need a session and the CSRF token in the X-CSRF-Token header (/session/token), like the other endpoints of the builder.
GET /frame-editor/node/{node}/export: the saved page as a file. Query:reference=1,media=1(with the media files),langcode=de(the same file, started from that translation),download=1(the browser saves it). Media files over the limit: status 422 anderrors.POST /frame-editor/node/{node}/export: what a client has:{"data": <layout>, "ids": ["h1"], "reference": false, "media": false, "drafts": true}. The editor uses this. Each language is its latest revision.POST /frame-editor/node/{node}/import:{"file": <the file, or its text>, "mode": "replace" | "insert", "message": "…", "save": true}. Needs Import Frame layouts and the right to edit the page. With"save": falsethe layout is returned for the editor and nothing is saved. The answer haswarnings, and what was added to the library or the media library (created) or used (reused). A file that cannot be used gives status 422 anderrors.
Schemas
/frame-editor/schema/layout.jsonis the same on every site: the format of the file, and the shape of an item. Public./frame-editor/schema/components.jsonis made from the components of the default theme: a definition for each (its props, its slots, the version it is at), the features every item can have (_spacing,_size,_align,_text,_background,_border,_position) with the names of the theme's tokens, and for each that can differ by screen width, a value per breakpoint underat. For people who build: it needs the access to create or edit a page that uses the editor.
Check the file with layout.json, and layout.content with components.json#/$defs/layout. An editor with JSON Schema support, or a script, then finds a made-up prop, a size that is not in the scale or a missing required prop. Both answers are cacheable and change with the configuration of the site and, after a cache rebuild, with its components. They use the same description as the AI assistant: the assistant gets the _spacing... part of components.json (without at, which it does not set) in its instructions.