`theme.json` has a formal [JSON Schema](https://json-schema.org) and a **schema version** that follows [semantic versioning](https://semver.org). Every theme declares the version it was written for, so Spotube always knows how to read it.

## Declare the schema version

```json
{
  "$schema": "https://docs.spotube.cc/schemas/theme/1.json",
  "schema": "1.0.0",
  "id": "my-theme",
  "name": "My Theme",
  "version": "1.0.0",
  "author": "You"
}
```

| Field | Meaning |
|---|---|
| `schema` | The theme **format** version (semver `MAJOR.MINOR.PATCH`) this theme is written for. Required in every package. |
| `version` | Your theme's own version. Unrelated to `schema`. |
| `$schema` | Optional editor hint. Points your editor at the JSON Schema for autocomplete and validation. |

The pre-semver value `"schema": 1` is still read as `1.0.0`.

## Use the JSON Schema

Two URLs are published:

| URL | Contents |
|---|---|
| `https://docs.spotube.cc/schemas/theme/1.0.0.json` | Exactly version 1.0.0. Never changes. |
| `https://docs.spotube.cc/schemas/theme/1.json` | The latest `1.x.y`. Use this in `$schema`. |

With the `$schema` line above, editors such as VS Code autocomplete every component and property name, and underline typos (`borderWidht`) as you type. The schema lists **every property of every component** and the slots and states each one supports. It is generated from the same tables the app compiles themes with, so it cannot drift from what the app accepts.

You can also validate from the command line or CI. [`@team-spotube/theme-tool`](/themes/creating-a-theme) does it for you in `spotube-theme check`; with [Ajv](https://ajv.js.org) directly:

```js
import Ajv2020 from 'ajv/dist/2020.js';
const validate = new Ajv2020({ strict: false }).compile(schema);
if (!validate(theme)) console.error(validate.errors);
```

## Release history

| Version | Added |
|---|---|
| 1.3.0 | In-house component slots: `mediaCard`, `mediaListTile`, `floatingPlayer`, `largePlayer`, `expandedPlayer`, `playerQueue`, `trackList`, `collectionHeader`, `featuredCarousel`, `screen`, `section`, `lyricsLine` and more, styled through `components.<name>.variants.<slot>`. |
| 1.2.0 | `updates`: GitHub release based update checks (`github` repository URL and `asset` archive name). |
| 1.1.0 | `assets.iconPack.images`: a PNG per icon role, so icon packs can come from any library. |
| 1.0.0 | First release. |

`1.1.0` is a real example of a **minor** release: every 1.0.0 theme works unchanged on a build that implements 1.1, and a theme that uses `images` declares `1.1.0` (the theme tool does this for you and keeps themes that don't need it at `1.0.0`). On a Spotube that only implements 1.0, a 1.1 theme still loads, its icon pack is ignored and a note is shown.

## What the version numbers promise

| Bump | When | What it means for themes |
|---|---|---|
| **MAJOR** | A breaking change: a property is removed, renamed or changes meaning. | A theme of another major is **refused** with a clear message. Authors migrate and bump `schema`. |
| **MINOR** | A backwards-compatible addition: a new token, component, property, function or asset kind. | Older themes keep working untouched. A theme written for a *newer* minor still loads on an older Spotube; parts that build doesn't know are ignored and a note is shown on the theme's card. |
| **PATCH** | A clarification or a bug fix in the schema or docs. | Invisible to themes. |

In practice:

| Spotube implements | Theme declares | Result |
|---|---|---|
| 1.3.0 | 1.0.0 | Loads normally. |
| 1.3.0 | 1.3.7 | Loads normally (patch is ignored). |
| 1.3.0 | 1.4.0 | Loads; unknown newer parts are ignored, with a warning. |
| 1.3.0 | 2.0.0 | Refused: "needs a newer Spotube". |
| 2.0.0 | 1.4.0 | Refused: "uses the outdated schema". |

Declare the **lowest** minor that contains every feature you use. A theme that only uses 1.0 features should say `1.0.0`, so it keeps validating against every 1.x schema and loads on every build.

## Rules for changes to the format

- Adding is a **minor**; removing or reinterpreting is a **major**. A major is a last resort, and Spotube keeps a deprecated property working for at least one major cycle with a warning.
- A new property must have a default that reproduces the old look, so existing themes are unaffected.
- Unknown top-level keys and unknown `assets` kinds never break a theme; unknown component properties are reported as warnings (typos surface instead of failing silently).
- The schema file, the version constant in the app and the example themes are updated together, and a test fails if the schema and the app disagree.

## For Spotube contributors

The source of truth is `themes/schema/theme.schema.json` in the Spotube repository. It is generated:

```bash
node tools/gen-theme-schema.mjs \
  composeApp/src/commonMain/kotlin/org/spotube/spotube/core/ui/theming/engine/GeneratedThemeProps.kt \
  composeApp/src/commonMain/kotlin/org/spotube/spotube/core/ui/theming/engine/ThemeDocument.kt \
  themes/schema/theme.schema.json
```

Change the format → bump `THEME_SCHEMA_VERSION` in `ThemeDocument.kt` → regenerate → copy the file to this site (`schemas/theme/<version>.json` and `schemas/theme/<major>.json`) and to the themes repository (`packages/theme-tool/schema/theme.schema.json`), then release a new `@team-spotube/theme-tool`.

[themes]: https://github.com/team-spotube/themes
