Key takeaways
- Merchant content is stored on the store as JSON keyed by the ids, block types and file names in your theme's schema, so changing one of those names cuts the content loose.
- Renaming or removing a setting id, a block type, a section file or a theme block file loses content; renaming a label or a schema name loses nothing.
- Changing a setting's default changes every placement left at the default, and Auditor's store check doesn't report it, so count those placements yourself first.
- The safe pattern for a rename is to add the new id beside the old one, move the values on the store, and remove the old id in a later pull request.
A Shopify theme's schema is an API, and merchant content is its stored data. When a merchant fills in a section in the theme editor, Shopify writes the values into the store's copy of templates/*.json, section groups such as sections/header-group.json, or config/settings_data.json for the theme settings. Each value is keyed by something your code defines: a setting id, a block type, or the name of a section or block file.
Change one of those keys and nothing migrates the stored data. Most repositories keep these files out of git, so the diff doesn't show the content either. Our earlier article covers how Auditor's store check catches this in review. This one goes through each kind of change: what it costs, and how to make it without losing anything.
Where the values live
A placed section in a template looks like this on the store:
{
"sections": {
"hero_8Kd2": {
"type": "image-banner",
"settings": { "heading": "Winter sale", "button_label": "Shop now" },
"blocks": {
"button_x1": { "type": "button", "settings": { "link": "shopify://collections/winter" } }
}
}
}
}Three names in there come from your code. image-banner is the file sections/image-banner.liquid, button is a block type (defined in the section's schema, or the file blocks/button.liquid for a theme block), and heading and button_label are setting ids. A setting a merchant never changed isn't stored at all. It renders the schema's default.
What each change does
| Change | What happens to saved content | Store check |
|---|---|---|
| Rename a setting id | Values under the old id are no longer read, and are dropped the next time the template or theme settings are saved | Reported, High |
| Remove a setting | Same as a rename | Reported, High |
| Change a setting's type, same id | The id is unchanged, but the stored value was written for the old type | Not reported |
| Change a setting's default | Every placement left at the default shows the new one; set values stay | Not reported |
| Remove a block type from a section's schema | Blocks of that type in that section stop rendering and lose their settings | Reported, High |
| Rename or delete a theme block file | Every placed instance of that block type, in any section, disappears; presets that name it break | Reported, High |
| Rename or delete a section file | Every placement stops rendering, with its settings and blocks | Reported, High |
| Remove a preset | Nothing placed is lost; the last preset going means merchants can no longer add the section | Last preset only, Low |
Rename a label, info or schema name | Nothing: merchants see these, but content isn't keyed by them | Nothing to report |
Two notes on the table. A placement that leaves a removed setting at its default isn't reported, because it stores no value and loses nothing. And removing one preset of several loses nothing, because content placed from a preset doesn't name it. Only the editor's Add section list does.
How the store check reports it
When a pull request removes one of these keys, Auditor reads the store's published theme for that key alone and comments on the line that removed it. A setting finding lists where it's set and the values merchants chose:
3 placements on the store set button_label; removing it loses those values On the published theme of
your-store, 3 placements of sectionimage-bannersetbutton_label, which this pull request removes or renames.
- Home page (
templates/index.json)- Product page (
templates/product.json)- Collection page (
templates/collection.json)Values:
Shop now(2),See the collection(1).
The check sees a renamed id as a removed one: in the schema, the old id is gone and a new one appeared, and nothing on the store holds the new one yet. A renamed section or block file is reported under its old name, with the new name in the finding. Theme settings are read from the store's config/settings_data.json, using the settings preset the store has chosen.
The check compares ids and file names. It doesn't compare types or defaults, so the two rows marked "Not reported" are yours to check.
Safe ways to make each change
Renaming a setting id. Usually you don't need to. Merchants never see the id, so change the label instead. If the id really has to change, do it in two pull requests:
- Add the new setting beside the old one, and read the new value with the old one as a fallback.
- Move the values on the store, then remove the old setting once nothing sets it.
{%- assign label = section.settings.cta_label | default: section.settings.button_label -%}Liquid's default also replaces false, so for a checkbox write default: section.settings.old_id, allow_false: true, or a merchant's "off" falls through to the old value.
Changing a setting's type. Treat it as a rename: add a new id with the new type, move the values, then remove the old one. Then no stored value is read under a type it wasn't written for.
Changing a default. Before you merge, find out how many placements are left at the old default. The Auditor MCP server's content_usage tool, given a section and a setting, counts how many placements set it and to what. The rest are at the default. If those pages should keep their current look, set the old value on them explicitly before you change the default.
Removing a block type or a setting. Find where it's used with content_usage, then move or delete that content on the store first, so the removal takes nothing a merchant still relies on. Or keep the schema entry and stop rendering it until the store no longer uses it.
Renaming a section or a theme block file. Keep the file name and change the schema's name, which is all the editor shows. If the file must move, keep the old file as a copy until the store's content uses the new one. A file in blocks/ is shared by every section that accepts it, so its instances can be anywhere on the store.
Removing the last preset. This is fine when the section is meant to stay where it already is, such as a main product section. Otherwise keep one preset so merchants can still add the section.
Limits
The check reads the store's published theme, not an unpublished theme you may be about to publish. A pull request that touches more than 40 schema files is checked for the first 40, and the check run says so. If the store can't be reached, the review goes on without the check and says why. For anything the check doesn't cover, the same reads are available to you or your coding agent through the MCP server before you open the pull request.
Frequently asked questions
Does changing a setting's label lose any merchant content?
No. Saved values are keyed by the setting id. The label, info text and the schema's name are only what the theme editor shows, so you can change them freely.
Why doesn't Auditor report a setting left at its default?
A placement left at the default stores no value for that setting, so removing the setting takes no merchant value with it.
Does Auditor catch a changed setting type or default?
No. The store check compares ids and file names. Use the MCP server's content_usage tool to see which placements set the setting and to what before you change either.
Can I keep reading a value after I remove its setting from the schema?
Don't rely on it. Keep the old setting in the schema while you move values to the new one, and remove it only once content_usage shows nothing sets it.