Shopify JSON Editing Workflow

Overview

Edit templates/*.json, JSON section data, config/settings_data.json and config/settings_schema.json using the target theme's existing types and schemas. Treat Liquid schemas as read-only. If a design needs new types or non-JSON code, explain the gap and propose the closest supported result.

When to use

Use for JSON templates, including alternate templates; existing theme-block composition; global settings definitions/values; and layout, content, color, typography, spacing, visibility or behavior exposed by existing schemas. Visual references may guide the closest JSON-supported composition.

When not to use

Exclude checkout branding/extensions, app extension code, Liquid templates, new sections/blocks/snippets, assets, JavaScript, CSS and Liquid-schema edits. Do not create files under those code paths. If a build generates JSON, read project guidance and edit its JSON/settings source of truth; non-JSON source work is outside this skill.

Quick start

1. Understand the request and discover valid types and parent-child edges.
2. Inspect optional matching examples, schemas and global design settings; build a setting-constraint ledger.
3. Compose JSON using valid types, settings and ordering.
4. Resolve a verified preview through $preview-shopify-theme, preserving source/store/theme and process identity.
5. Inspect the edited routes at desktop/mobile widths and correct mismatches.
6. Parse/schema-validate locally; perform strict upload validation only when the real upload is authorized.

Workflow

Step 1 — Understand user requirements

Extract layout, columns/rows, content types, hierarchy, spacing, alignment, colors and responsive intent from text or images. Static images do not establish exact breakpoints, font sizes or pixel spacing; name that uncertainty.

Design images and mockups

• Infer section structure, stacking order, media placement and qualitative spacing from screenshots/Figma exports. Verify all Shopify types, keys and enum values against the target theme.
• For full-page or brand-specific work, inspect global typography, palette, schemes/gradients, buttons, radii, borders and spacing first. Skip global changes only for explicit template-only work or globals that already match.
• Use source images only to locate media blocks. Do not copy, crop, recreate, download, generate or invent assets from a mockup. Leave valid image/media settings blank unless the user supplies existing asset filenames, Shopify references, selected settings or files explicitly intended for storefront use.
• Report details requiring arbitrary typography, CSS, markup or new behavior as theme-code gaps; deliver the closest existing schema-supported structure.

Step 2 — Discover allowed block types

Do this before emitting any type:

1. List blocks/; confirm each basename/type in the target schema.
2. Read {% schema %} for every section and nested parent block. Validate each immediate parent-child edge. Existing content blocks may need an allowed wrapper rather than direct nesting.
3. Treat explicit blocks arrays as allowlists. @theme permits general theme blocks; specific lists permit only their listed types and any listed @app. Resolve template section types through sections/<type>.liquid.
4. _-prefixed block types may be private/static even with presets. Before nesting one under @theme, verify precedent in target templates/presets; parents may need explicit declarations. Never modify Liquid to allow it: choose another valid block or report the gap.
5. Use only the resulting allowed types. Copy a working target pattern or suggest the closest existing type when the requested layout is unavailable.

Step 3 — Check bundled examples (optional)

Follow Choosing the best example to reference: compare the theme name, guide and block basenames, then open at most one matching example. If none fits, use target templates. Every copied type/setting still needs target-schema verification.

Step 4 — Map requirements to real blocks

Choose layout/content blocks from the allowed set. Map template-level sections to existing section files. Use scoped Jevgrep questions when available, verify actual excerpts/files/schemas, and use direct reads/rg for exact matches or fallback. Do not install search tools or request credentials.

Step 5 — Analyze block and section schemas

Read each {% schema %} for allowed children, settings, defaults and presets. Build a parent-child map for every emitted nesting level.

Build a schema settings ledger before writing JSON

Record every global, section and block setting you will emit:

Consult the selected theme example for upload-specific traps; copied settings still need validation against their destination type.

Run a global settings pass for new pages and mockups

Before composing a new or heavily revised page, read config/settings_schema.json and active current/color_schemes in config/settings_data.json. Compare body/heading fonts, base size, scale, line heights/case, button typography, foreground/background/button/link/overlay colors, gradients, radii, borders, margins and gaps.

Update mismatched globals unless the user requests template-only work; record why matching globals remain unchanged. Prefer responsibility in this order:

1. Global: brand typography, palette, named schemes, gradients, buttons, radii, borders and spacing defaults.
2. Section: composition, scheme assignment, width, margins, alignment and behavior.
3. Block: intentional local exceptions, visibility and display-heading art direction.

Use default typography tokens for ordinary body, label, button and product-card text. Reserve custom block sizes for intentional display headings or requested exact local art direction. Prefer complete named color schemes over repeated overrides; mirror the active data shape and use schema-supported assignment settings such as color_type: "custom"/color_scheme_custom only when present.

Step 6 — Apply theme design controls

• Use schema-defined settings. A custom_css setting is allowed only when already exposed and explicitly requested. Its entries must be complete selector rules, such as .rte { text-transform: uppercase; }; never standalone declarations or stylesheet edits.
• Global definitions belong in settings_schema.json, active values in settings_data.json. Preserve current structure, group conventions, IDs, types, defaults/options and complete scheme objects. Add no arbitrary tokens/classes or non-JSON behavior through schema changes.
• Use section/block settings for a contained change that should not affect the whole store. Validate every destination key, type, range, select and enum-like value; a setting valid on one block may be invalid on another.
• Respect parent inheritance; override local color/type/borders only when the design needs it and the schema supports it. Verify restricted container children and nesting against the same target theme or a verified matching example.

Step 7 — Compile JSON structure

Follow Shopify's JSON shape and applicable project rules, including .cursor/rules/templates.mdc, blocks.mdc or schemas.mdc when supplied.

Template structure:

{
  "sections": {
    "<sectionId>": {
      "type": "<sectionType>",
      "settings": {},
      "blocks": {
        "<blockId>": {
          "type": "<blockType>",
          "name": "t:blocks.block_name",
          "settings": {},
          "blocks": {},
          "block_order": []
        }
      },
      "block_order": ["<blockId>"]
    }
  },
  "order": ["<sectionId>"]
}

Block instance IDs: use descriptive role prefixes matching target conventions, adding a unique suffix when needed. Instance IDs cannot start with _, even when private block types do; use grid_products_best for an instance of "type": "_grid-products". Keep IDs unique in template/nested scope as required.

Static blocks and block_order: declare static children in blocks, never sibling block_order. The order lists existing dynamic/reorderable siblings only; for static-only parents, use [] or omit it when the target pattern permits. Top-level order lists the sections to render.

Use actual layout settings and the theme's color/spacing system. Follow its translated block-name convention, such as "t:blocks.image".

Whole-template replacement guard: strip Shopify's generated-file comment header, parse and verify exactly one top-level object; never append old template content after the closing brace.

node -e "const fs=require('fs'); const s=fs.readFileSync('templates/index.json','utf8').replace(/^\/\*[\s\S]*?\*\/\s*/, ''); JSON.parse(s);"

Richtext content rules: supported tags are p, h1–h6, ul, ol, li, a, br, strong, em, span. Shopify sanitizes rich text/richtext; do not add style or inline class attributes. Use existing typography/richtext settings. Unsupported colored text is a theme-code gap, not permission to add inline styles, Liquid, stylesheets or assets.

Step 8 — Preview and visually verify

Parsing, schema validation and upload success do not prove rendering or behavior. Verify every visual edit when the target preview is accessible.

Consume the verified preview target

Use an existing verified preview or $preview-shopify-theme for simulation (references/tools/local-storefront.md) or Shopify development (references/tools/shopify-cli.md). Setup verifies source, store, theme ownership, authorization, process lifetime and browser access; never infer that another development theme is safe to overwrite. Simulation needs no Shopify credentials and does not replace authorized strict upload validation.

Preserve the verified URL's preview parameters and open the exact edited route. Copy authorized JSON into its disposable theme if needed, wait for reload/sync and verify the final artifact. Pause continuing remote sync before changes outside the authorized store/source/theme scope. If unreachable or unverified, retain JSON/schema evidence and mark visual verification blocked.

Run the visual correction loop

1. Save and wait for successful local reload/restart or authorized sync. Rendering/upload errors fail that iteration.
2. Open the edited route, rather than only the editor, mockup, reference site or another template. Inspect desktop (for example 1440 × 1000), mobile (375 × 812) and requested breakpoints.
3. Verify section/block/content/control order; loaded media with nonzero dimensions; no hidden required content; expected grid/slider columns, static/disabled containers, alignment, spacing, typography, colors, borders and buttons. Check unexpected document.documentElement.scrollWidth beyond clientWidth.
4. Exercise affected sliders, pagination, variants, add-to-cart and responsive controls.
5. Compare against the supplied reference, correct settings and repeat. Completion evidence comes from the edited target. After the final fix, recheck both viewports.

Record target/theme, route, viewports, final successful reload/sync, observations and remaining JSON-only gaps. Distinguish validation from visual verification.

Step 9 — Validate

Reconcile every requested change with its exact file, setting/schema, parsed final value and expected rendered result. Test distinct affected routes/states at recorded viewports; name unverified assertions when the preview is unavailable. Rerun affected assertions after source/preview changes; unrelated routes/settings cannot prove a prior defect fixed.

For local-only work, parse/schema-validate and record browser evidence. State that Shopify upload validation was not performed; it is not required for a local test store.

When the real upload is requested and authorized, skip Theme Check for JSON template edits and use strict upload validation:

shopify theme push --strict --only templates/<name>.json

For the homepage:

shopify theme push --strict --only templates/index.json

These commands upload on success; they are not dry runs. Avoid interactive theme selection. If an owned npm run dev/shopify theme dev process supplies preview_theme_id=<theme_id>, use that verified authorized destination:

shopify theme push --strict --only templates/<name>.json --theme <theme_id>

Without a verified ID, ask which theme to target before pushing. Prefer existing dev logs over starting a duplicate server. Save/touch the template to trigger authorized sync; inspect Failed to upload file "templates/<name>.json" to remote theme and the following error, fix that error class and retry until successful sync/no new error. Treat errors after Theme upload complete as authoritative even with exit code 0. Retain the exact error and add the local guard/checklist entry before retrying.

Validation checklist

• JSON parses as exactly one object after header removal; no appended prior template remains.
• Instance IDs are unique in scope and do not start with _; types may use private prefixes.
• order/block_order reference actual siblings to render; static blocks are absent from block_order.
• Types exist and each immediate edge is allowed; private _ types are explicitly listed in every parent, not only covered by @theme.
• Setting keys/types, in-bounds range steps (including hidden values) and exact select options match destination schemas.
• Global schema/data remain aligned, including range/select/type constraints and complete color schemes. Full-page work includes a global pass or a recorded reason to leave matching globals unchanged.
• Mockup imagery remains blank unless explicit storefront assets were supplied; richtext has no inline style/class attributes.
• Final source loaded or synced to the verified preview before desktop/mobile inspection. No introduced overflow, hidden content, unloaded media or broken layout remains; affected interactions and final post-fix states were retested.
• Handoff distinguishes schema/upload validation from visual verification and names blocked evidence.

Error handling

Further reading

• Shopify platform reference: official documentation, filenames and limits.
• Example catalog: choose a matching bundled pattern.
• In the target repo, follow applicable .agent/rules/templates.mdc, blocks.mdc and schemas.mdc when present.

Sources

Review the corresponding procedure when these official sources change: