Homey SDK v3 rules — sourced, tested, automated (P2964)
Generated by node tools/ci/homey-sdk-rules-doc.js from tools/ci/homey-sdk-rules.js. Do not edit the table by hand.
- 54 rules: 36 blocking, 18 report-only.
- Facts snapshot: node-homey-lib 2.52.0 at commit
a5ebb0f(2026-10-20): 75 device classes, 184 system capabilities, 19 battery types, 184 locales, 13 permissions. - Every rule is written in our own words. The validator code is read, never copied; facts (lists, minimum versions) come from the refresh script.
Levels
Athom validates at three cumulative levels (homey app validate --level debug|publish|verified):
| Level | Meaning | Our CI |
|---|---|---|
| debug | Checked on every build/run | blocking |
| publish | Additionally checked by homey app publish and Athom processing | blocking |
| verified | Only for Verified Developers | report-only (we are not verified) |
| project | Lessons from our own Athom history or hygiene, not an Athom rule | blocking only when it caused a real refusal, report-only otherwise |
Where it runs
node tools/ci/homey-sdk-rules.js: uses.homeybuild/app.jsonwhen present (build mode), otherwise the rootapp.jsonplus every driver'sdriver.flow.compose.json(compose mode).- pre-commit (
.githooks/pre-commit): compose mode, blocking rules only. pr-gate.yml: compose mode, blocking, plus a JSON report artifact.homey-sdk-rules-refresh.yml: weekly diff of node-homey-lib facts, the homey CLI and the SDK docs; opens a draft PR (paths are[skip ci]-safe).- Kill switch:
HOMEY_SDK_RULES_DISABLED=1. Report-only run:--report-only.
Recent changes picked up (2026)
| Date | Change | Rule |
|---|---|---|
| 2026-05-21 | Capability titleShort requires compatibility >=13.2.1 (node-homey-lib 26786f0) | SDK-M14 |
| 2026-08-05 | meter_power and meter_gas default decimals raised to 3 (c7b0e6f); data only | — |
| 2026-08-27 | Capability uiState validated, requires >=13.5.0 (92e402a) | SDK-M14 |
| 2026-09-29 | .homeyignore and .gitignore evaluated independently; **/ matches zero folders (e3c951e, 8887eef) | SDK-P05 |
| 2026-09-29 | homey CLI 4.5.3: homey app review validates at publish level first (a7435cc) | — |
| 2026-10-09 | homey CLI 4.6.0: cloud added as a discovery strategy | — |
| 2026-10-21 | homey CLI 4.6.1: homey-api 3.21.0, Homey-bound sign-in tokens (210c3d5) | — |
| 2026-10-10 | Our master was refused for a Flow card using {arg} instead of [[arg]] | SDK-F03 |
Not documented anywhere official: a size limit for app.json or the archive. SDK-P04 is our own observation (report-only).
Sources
- SDK docs: manifest, Flow, Flow arguments, capabilities, settings, energy, Zigbee, i18n, assets, guidelines, updates/changelog, Homey Cloud.
- Validator: athombv/node-homey-lib
lib/App/index.jsandassets/app/schema.json; commit history. - CLI: athombv/node-homey.
- Firmware changelogs and developer blog: watched by the weekly refresh (page hash diff), no rule derived yet.
Rules
| Rule | Area | Level | CI | Rule (our wording) | Source · since |
|---|---|---|---|---|---|
| SDK-M01 | manifest | debug | block | App id is a reverse-domain string: at least two dot-separated parts, only letters, digits, "_", "-" and ".". | source · SDK3 |
| SDK-M02 | manifest | debug | block | version is plain semver x.y.z; pre-release suffixes (-rc.1, -beta) are refused. | source · SDK3 |
| SDK-M03 | manifest | debug | block | compatibility is a semver range whose minimum is at least 5.0.0 for SDK 3 apps. | source · SDK3 |
| SDK-M04 | manifest | debug | block | sdk must be 3 (older SDKs cannot be published as new versions). | source · SDK3 |
| SDK-M05 | manifest | publish | block | category is required at publish and every entry must be one of the App Store categories. | source · SDK3 |
| SDK-M06 | manifest | publish | block | brandColor is required at publish and must be dark enough for white icons (perceived brightness <= 184). | source · SDK3 |
| SDK-M07 | images | publish | block | App images.small (250x175) and images.large (500x350) are required, .png/.jpg/.jpeg, exist with exact case, real image bytes, exact pixel size. xlarge (1000x700) is optional and checked by SDK-M16. | source · SDK3 |
| SDK-M08 | permissions | debug | block | permissions must be known Homey permissions or homey:app:<id>; homey:app:com.athom.homeyscript is forbidden. | source · SDK3 |
| SDK-M09 | permissions | verified | report | homey:manager:speech-input is unsupported (refused for verified); homey:manager:api triggers a longer review. | source · SDK3 |
| SDK-M10 | platforms | debug | block | platforms contains only "local" and/or "cloud"; platformLocalRequiredFeatures cannot be combined with cloud. | source · SDK3 |
| SDK-M11 | platforms | verified | report | Verified apps must declare platforms and support (https:// or mailto:). | source · SDK3 |
| SDK-M12 | manifest | debug | block | name is an i18n object with an "en" entry; author.name is required. | source · SDK3 |
| SDK-M13 | translations | debug | block | Every /locales/<code>.json file uses an allowed ISO 639-1 code and parses as JSON. | source · SDK3 |
| SDK-M14 | capabilities | debug | block | NEW: capability titleShort needs compatibility >=13.2.1 and uiState needs >=13.5.0, both in app capabilities and driver capabilitiesOptions. | source · homey-lib 2026-05-21 (titleShort) / 2026-08-27 (uiState) |
| SDK-M15 | manifest | debug | block | env.json (if shipped) holds only UPPERCASE keys with string values. | source · SDK3 |
| SDK-C01 | capabilities | debug | block | Custom capability ids must not contain "." (reserved for sub-capabilities such as onoff.button1). | source · SDK3 |
| SDK-D01 | drivers | debug | block | Each driver class is a known device class and its minimum compatibility is met by the app. | source · SDK3 |
| SDK-D02 | capabilities | debug | block | Each driver capability (before any ".suffix") is a system capability or defined by the app; system capabilities respect their minimum compatibility. | source · SDK3 |
| SDK-D03 | energy | publish | block | A driver using measure_battery or alarm_battery must declare energy.batteries (array) unless it is a homeBattery or electricCar. | source · SDK3 |
| SDK-D04 | energy | debug | block | energy.batteries entries must be known battery types (CR2032, AA, AAA, INTERNAL, OTHER…). | source · SDK3 |
| SDK-D05 | energy | debug | block | energy.cumulativeImported/ExportedCapability and meterPowerImported/ExportedCapability may only point at meter_power or meter_power.<sub>. | source · SDK3 energy v2 |
| SDK-D06 | energy | project | report | energy.approximation values (usageOn/usageOff/usageConstant) should be non-negative numbers in W. | source · SDK3 |
| SDK-D07 | images | publish | block | Driver images.small (75x75) and images.large (500x500) are required at publish with exact size; xlarge is checked by SDK-D20. | source · SDK3 |
| SDK-D08 | drivers | debug | block | Every driver id has a matching /drivers/<id> folder (case-sensitive). | source · SDK3 |
| SDK-D09 | capabilities | debug | block | capabilitiesOptions.<cap> must be an object. | source · SDK3 |
| SDK-D10 | capabilities | project | report | capabilitiesOptions keys should match a capability the driver actually lists (otherwise the option is dead). | source · SDK3 |
| SDK-D11 | settings | debug | block | Driver setting ids are strings and setting types are one of the documented types (text, password, textarea, label, number, slider, radio, dropdown, checkbox, group). | source · SDK3 |
| SDK-D12 | settings | debug | report | Setting ids should not start with reserved prefixes (homey:, zw_, zb_, mtr_, energy_, zone_…) — Homey warns. | source · SDK3 |
| SDK-D13 | settings | project | report | Setting ids are unique inside one driver (a duplicate silently shadows the other). | source · SDK3 |
| SDK-D14 | platforms | debug | block | A driver may only list platforms the app lists; cloud drivers cannot use lan, matter or rf868 connectivity. | source · SDK3 |
| SDK-D15 | platforms | verified | report | Verified apps need platforms and connectivity on every driver. | source · SDK3 |
| SDK-D16 | zigbee | debug | block | Zigbee fingerprint shape: manufacturerName and productId are a non-empty string or an array of non-empty strings (an empty array is reported by SDK-D21); endpoints is an object keyed by endpoint number with clusters/bindings as arrays of integers. | source · SDK3 |
| SDK-D17 | zigbee | project | report | No duplicated manufacturerName inside one driver (case-insensitive), padded forms kept verbatim. | source · project P2941 |
| SDK-D18 | drivers | debug | block | driver.discovery, when a string, must name an entry of app.discovery. | source · SDK3 |
| SDK-D19 | drivers | debug | block | Driver ids are unique and every driver has a name.en. | source · SDK3 |
| SDK-M16 | images | project | report | Optional app images.xlarge (1000x700), when declared, should exist and have the exact size. | source · SDK3 |
| SDK-D20 | images | project | report | Optional driver images.xlarge (1000x1000), when declared, should exist and have the exact size. | source · SDK3 |
| SDK-D21 | zigbee | project | report | A Zigbee driver with an empty manufacturerName or productId list can never match a device during pairing. | source · SDK3 |
| SDK-F01 | flow | debug | block | Flow card ids are unique per type (triggers / conditions / actions), driver cards included after compose. | source · SDK3 |
| SDK-F02 | flow | debug | block | titleFormatted (every language) references each argument exactly once as [[name]], no unknown names; the implicit first device argument of a driver card is excluded; droptoken counts as an argument. | source · SDK3 titleFormatted |
| SDK-F03 | flow | project | block | An argument is referenced as [[arg]], never as {arg}, in titleFormatted (the {arg} form got master refused on 2026-10-10). Token names in braces are left alone. | source · project 2026-10-10 Athom refusal |
| SDK-F04 | flow | verified | report | Cards with arguments need titleFormatted (warning now, required for verified). | source · SDK3 |
| SDK-F05 | flow | verified | report | Every non-implicit argument has a title (required for verified). | source · SDK3 |
| SDK-F06 | flow | debug | block | Argument types are the documented ones (text, autocomplete, number, range, date, time, dropdown, checkbox, color, device, multiselect, code); names are unique per card. | source · SDK3 |
| SDK-F07 | flow | debug | block | multiselect arguments need compatibility >=12.5.0. | source · homey-lib (Homey 12.5.0) |
| SDK-F08 | flow | debug | report | Tokens declare a type (boolean, number, string, image); missing type defaults to string and will become mandatory. | source · SDK3 |
| SDK-F09 | flow | debug | block | A card platforms list may only contain platforms the app supports. | source · SDK3 |
| SDK-F10 | flow | debug | block | Every card has a string id and a title with an "en" entry. | source · SDK3 |
| SDK-P01 | publishing | publish | block | .homeychangelog.json is valid JSON: keys are x.y.z versions, values are i18n objects with an "en" string. | source · SDK3 |
| SDK-P02 | publishing | project | report | The changelog should have an entry for the current version (Athom shows it as "What's new"). | source · SDK3 |
| SDK-P03 | publishing | publish | block | node_modules inside the built app must contain no symbolic links (npm link leftovers). | source · SDK3 |
| SDK-P04 | publishing | project | report | Unofficial: keep the compact app.json under 5 MB (Athom processing stalls on oversized manifests in our history). No official limit is documented. | source · project 2026-05-31 |
| SDK-P05 | publishing | project | report | NEW: .homeyignore and .gitignore are evaluated independently and "**/" now matches zero directories — a negation (!x) in one file no longer re-includes files ignored by the other. | source · homey-lib 2026-09-29 (e3c951e, 8887eef) |
| SDK-P06 | publishing | verified | report | README.txt is plain text, short, without URLs or a changelog. | source · Guidelines 1.3 |