Schema and versioning
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"
}
The pre-semver value "schema": 1 is still read as 1.0.0.
Use the JSON Schema
Two URLs are published:
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
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
In practice:
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
assetskinds 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.