Schema and versioning

The theme.json JSON Schema, the semantic version every theme declares, and how compatibility works across releases.

theme.json has a formal JSON Schema and a schema version that follows semantic versioning. Every theme declares the version it was written for, so Spotube always knows how to read it.

Declare the schema version

{
  "$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 does it for you in spotube-theme check; with Ajv directly:

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:

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.