Shopify Section Schema Won’t Save: Fix JSON Errors

Shopify section schema will not save: invalid JSON in schema tag

When you click Save in the theme editor and the modal says “Invalid JSON in schema tag”, the whole section becomes unusable. This error stops any further edits and can break page rendering. Below is a concrete debugging session that gets your section back to a working state.

Symptom

• The theme editor shows a red banner: “Invalid JSON in schema tag (line X, column Y)”.
• When you open the section file (sections/hero.liquid) the line highlighted in the editor contains the {% schema %} block.
• The section disappears from the page preview, and the console may log SyntaxError: Unexpected token if you open the preview in Chrome DevTools.

Cause

Shopify parses the content of the {% schema %} tag as strict JSON. Any of the following will cause the parser to throw:

1. Trailing commas – JSON does not allow a comma after the last property.
2. Unquoted keys or values – keys must be double‑quoted strings, and string values need quotes.
3. Smart quotes or other non‑ASCII characters – copying from Word or Google Docs often replaces straight quotes with “smart” ones.
4. Missing closing braces/brackets – a common copy‑paste error.
5. Incorrect nesting of arrays/objects – e.g., putting a settings object inside another settings array.

A common mistake is to add a comment inside the JSON block (// comment) because Liquid permits comments, but the JSON parser does not.

Fix

Follow these exact steps to repair the schema:

1. Open the section file

   • In the admin, go to Online Store → Themes → Actions → Edit code.
   • Locate the offending file under sections/ (e.g., hero.liquid).

2. Copy the raw schema to a temporary editor

   {% schema %}
   {
     "name": "Hero banner",
     "settings": [
       {
         "type": "image_picker",
         "id": "bg_image",
         "label": "Background image"
       },
       {
         "type": "text",
         "id": "title",
         "label": "Title",
         "default": "Welcome"
       }
     ]
   }
   {% endschema %}
   

   Paste the block (including the opening and closing {% schema %} tags) into a plain‑text editor that shows hidden characters (VS Code, Sublime, etc.).

3. Validate the JSON

   • Remove the {% schema %} and {% endschema %} lines, leaving only the JSON.
   • Use an online validator like https://jsonlint.com/ or the built‑in VS Code JSON validation (save file with .json extension).
   • Fix any highlighted issues: delete trailing commas, replace smart quotes with straight quotes, ensure all keys/values are quoted.

4. Re‑insert the cleaned JSON

   • Copy the validated JSON back into the original file, including the {% schema %} and {% endschema %} tags.
   • Make sure there is exactly one newline before {% schema %} and after {% endschema %} – extra whitespace does not break JSON but keeps the file tidy.

5. Save the file

   • Click Save in the code editor.
   • If the banner disappears, repeat step 3 – a hidden character (e.g., zero‑width space) may still be present.

Example of a broken schema and its corrected version

Broken (causes error)

{% schema %}
{
  "name": "Hero banner",
  "settings": [
    {
      "type": "image_picker",
      "id": "bg_image",
      "label": "Background image", // <-- comment not allowed
    },
    {
      "type": "text",
      "id": "title",
      "label": "Title",
      "default": "Welcome",
    }
  ], // trailing comma
}
{% endschema %}

Corrected

{% schema %}
{
  "name": "Hero banner",
  "settings": [
    {
      "type": "image_picker",
      "id": "bg_image",
      "label": "Background image"
    },
    {
      "type": "text",
      "id": "title",
      "label": "Title",
      "default": "Welcome"
    }
  ]
}
{% endschema %}

Quick tip for future edits

When adding new settings, always add them as a new object inside the settings array and end the line without a comma if it is the last entry.

Verify

1. Return to Online Store → Themes → Customize.
2. Open a page that uses the edited section. The section should render with its default values.
3. Open the Theme editor console (right‑click → Inspect → Console) and confirm there are no “Invalid JSON” errors.
4. Click Save again; the banner at the top of the editor should disappear.

If the error persists, repeat the validation step with a fresh copy of the schema – sometimes a stray invisible character slips in when copying from a rich‑text source.

Prevent

• Never write comments inside the JSON block. If you need documentation, place a Liquid comment outside the {% schema %} tags:

  {%- comment -%}
  This section displays the hero banner on the homepage.
  {%- endcomment -%}
  {% schema %}
  ...
  {% endschema %}
  

• Use a JSON linter as part of your development workflow. VS Code’s built‑in JSON validation will flag errors before you push to production.
• Keep a master copy of your schema in a .json file in your repo. When you need to edit, modify the file, validate, then paste back into the Liquid file.
• Avoid copy‑pasting from word processors. If you must, paste first into a plain‑text editor to strip formatting.
• Enable “Show invisible characters” in your code editor to spot zero‑width spaces or stray line‑breaks.

Frequently asked questions

Why does the error point to a line that looks fine in the editor?

The JSON parser counts characters after the Liquid tags are stripped, so the line number often reflects the position inside the JSON block, not the surrounding Liquid code.

Can I use single quotes in the schema JSON?

No. JSON strictly requires double quotes for keys and string values. Using single quotes will trigger the same “invalid JSON” error.

Will a missing type attribute break the whole schema?

Yes. Every setting object must contain a type field that matches one of Shopify’s supported types (e.g., text, image_picker). Omitting it stops the parser.

Does Shopify limit the size of a schema block?

There is no hard limit, but extremely large schemas can make the editor sluggish. If you exceed 10 KB, consider splitting the section into multiple reusable blocks.

Related reading

• Liquid error: unknown tag "schema"
• Metafields not showing in Liquid
• Shopify section schema development — our service page

Need a hand?

If the steps above don’t resolve the issue, our team can dive into your theme and fix the schema in minutes. Reach out via our contact page for a quick audit.