theme.json reference

theme.json is the theme’s manifest. It declares what a merchant can configure, what sections they can compose, and the two versions the platform tracks.

{
  "sdk": "1.0",
  "version": "1.0.0",
  "name": "aurora",
  "description": "A minimal multi-vertical theme.",
  "publicSettings": [ /* … */ ],
  "sections": [ /* … */ ]
}

Top-level fields

Field	Meaning
sdk	The contract version your theme targets. Must be a known version.
version	Your theme’s semver release version.
name	Machine name of the theme.
description	Short marketplace description.
publicSettings	The settings a merchant can edit in the customizer.
sections	The catalog of composable sections.

publicSettings

Each entry becomes a control in the theme customizer and a value on the settings object in Liquid.

{
  "type": "color",
  "name": "accent_color",
  "label": { "en": "Accent color", "ar": "لون التمييز" },
  "value": "#6d28d9"
}

Read it in Liquid as settings.<name>:

<div style="--accent: {{ settings.accent_color }}">…</div>

Conditional settings use showIf to hide (and skip validation of) a control until another setting has a given value.

Setting types

Type	Value	Notes
text textarea richtext	string or {lang: string}	richtext renders with | raw and is sanitized on every save.
url video_url	string	url is scheme-gated (the XSS boundary) — http(s), mailto, tel, or a /store-path.
color	CSS color string
number range	number	range honors min/max.
checkbox	boolean
image	string (asset URL) or null
select	one of the declared options
font_picker (fonts)	font name string
list	array of item objects	Repeater; declare item fields under settings.
page blog_post	a resource id (UUID)	Resolved to { title, url, … } at render.
products categories	array of ids	Resolved to localized resource objects.
category_products	one category id	Resolves the category and its products.
menu	a menu handle string	Resolves to a nav tree — see Menus.
products_by	{ source, tag?, brand? }	A smart product list — see Dynamic sources.
blog_posts	{} / null	Latest published posts — see Dynamic sources.

Labels are localized objects. value is the default. The dynamic-source types (menu, products_by, blog_posts) and the resource pickers are resolved by the server into localized, currency-correct data before render, so a theme offers a data-driven section without hardcoding ids or hand-picking content.

sections

The catalog of section types a merchant can add to composable templates. Each has a path and its own settings schema; the partial ships at views/sections/<path>.liquid (the platform resolves that path and hands it back as section.partial). A section may also declare blocks (mixed-type child items) and a preset (demo content on add). See Sections & blocks.

{
  "path": "hero",
  "name": { "en": "Hero", "ar": "الواجهة" },
  "settings": [ { "type": "text", "name": "title" } ],
  "blocks":   [ { "type": "cta", "name": { "en": "Button" }, "settings": [ { "type": "url", "name": "href" } ] } ],
  "preset":   { "settings": { "title": "Welcome" } }
}