Shopify / Shopify/theme-tools

ValidSettingsKey: does not validate section settings in template JSON files

Open
#1,239 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
234
Forks
92
Avg merge
1d 3h
Merged PRs (30d)
6

Description

Summary

The existing ValidSettingsKey check validates settings keys inside {% schema %} presets and defaults within Liquid section files. However, it does not validate settings keys in template JSON files (e.g. templates/page.json), where sections are instantiated with their actual store settings.

This means a typo in a setting key in a template JSON goes completely undetected by Theme Check.

Steps to reproduce

  1. Create a section sections/main-page.liquid with a schema containing a setting with "id": "heading_tag"
  2. In templates/page.json, reference that section with a typo in the settings key:
{
  "sections": {
    "main-page": {
      "type": "main-page",
      "settings": {
        "heading_tagg": "h1"
      }
    }
  },
  "order": ["main-page"]
}
  1. Run shopify theme check

Expected behavior

Theme Check reports an error or warning similar to:

Setting 'heading_tagg' does not exist in 'sections/main-page.liquid'.

Actual behavior

No error or warning is reported. The invalid key is silently ignored. The setting has no effect at runtime — which is especially hard to debug during a section schema refactor or key rename.

Context

The existing ValidSettingsKey check operates on SourceCodeType.LiquidHtml and validates settings in the presets and default blocks of a section's own {% schema %}. It does not cover section instances in template JSON files.

A complementary check (or an extension of ValidSettingsKey) would need to:

  • Target SourceCodeType.JSON template files
  • For each section instance, resolve the corresponding .liquid file
  • Parse its {% schema %} and collect valid setting IDs
  • Report any key in settings that does not match a valid setting ID

Why this matters

This gap becomes critical in multi-store theme workflows where template JSON files are store-specific and diverge from the main code branch. A renamed setting key in Liquid will silently stop working on any store whose template JSON still references the old key — with no tooling to catch it.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the existing ValidSettingsKey check and how Theme Check handles SourceCodeType.JSON. Trace template JSON section instances to the corresponding Liquid section schema, then verify the existing shopify theme check reproduction reports unknown settings keys. Done means invalid keys such as heading_tagg are reported while valid settings remain accepted.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.