Universal Tuya docsHomeSupported devicesRequest a deviceFAQChangelogArchitectureKnowledge baseCreditsSourcesContributing

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.

Levels

Athom validates at three cumulative levels (homey app validate --level debug|publish|verified):

LevelMeaningOur CI
debugChecked on every build/runblocking
publishAdditionally checked by homey app publish and Athom processingblocking
verifiedOnly for Verified Developersreport-only (we are not verified)
projectLessons from our own Athom history or hygiene, not an Athom ruleblocking only when it caused a real refusal, report-only otherwise

Where it runs

Recent changes picked up (2026)

DateChangeRule
2026-05-21Capability titleShort requires compatibility >=13.2.1 (node-homey-lib 26786f0)SDK-M14
2026-08-05meter_power and meter_gas default decimals raised to 3 (c7b0e6f); data only—
2026-08-27Capability 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-29homey CLI 4.5.3: homey app review validates at publish level first (a7435cc)—
2026-10-09homey CLI 4.6.0: cloud added as a discovery strategy—
2026-10-21homey CLI 4.6.1: homey-api 3.21.0, Homey-bound sign-in tokens (210c3d5)—
2026-10-10Our 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

Rules

RuleAreaLevelCIRule (our wording)Source · since
SDK-M01manifestdebugblockApp id is a reverse-domain string: at least two dot-separated parts, only letters, digits, "_", "-" and ".".source · SDK3
SDK-M02manifestdebugblockversion is plain semver x.y.z; pre-release suffixes (-rc.1, -beta) are refused.source · SDK3
SDK-M03manifestdebugblockcompatibility is a semver range whose minimum is at least 5.0.0 for SDK 3 apps.source · SDK3
SDK-M04manifestdebugblocksdk must be 3 (older SDKs cannot be published as new versions).source · SDK3
SDK-M05manifestpublishblockcategory is required at publish and every entry must be one of the App Store categories.source · SDK3
SDK-M06manifestpublishblockbrandColor is required at publish and must be dark enough for white icons (perceived brightness <= 184).source · SDK3
SDK-M07imagespublishblockApp 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-M08permissionsdebugblockpermissions must be known Homey permissions or homey:app:<id>; homey:app:com.athom.homeyscript is forbidden.source · SDK3
SDK-M09permissionsverifiedreporthomey:manager:speech-input is unsupported (refused for verified); homey:manager:api triggers a longer review.source · SDK3
SDK-M10platformsdebugblockplatforms contains only "local" and/or "cloud"; platformLocalRequiredFeatures cannot be combined with cloud.source · SDK3
SDK-M11platformsverifiedreportVerified apps must declare platforms and support (https:// or mailto:).source · SDK3
SDK-M12manifestdebugblockname is an i18n object with an "en" entry; author.name is required.source · SDK3
SDK-M13translationsdebugblockEvery /locales/<code>.json file uses an allowed ISO 639-1 code and parses as JSON.source · SDK3
SDK-M14capabilitiesdebugblockNEW: 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-M15manifestdebugblockenv.json (if shipped) holds only UPPERCASE keys with string values.source · SDK3
SDK-C01capabilitiesdebugblockCustom capability ids must not contain "." (reserved for sub-capabilities such as onoff.button1).source · SDK3
SDK-D01driversdebugblockEach driver class is a known device class and its minimum compatibility is met by the app.source · SDK3
SDK-D02capabilitiesdebugblockEach driver capability (before any ".suffix") is a system capability or defined by the app; system capabilities respect their minimum compatibility.source · SDK3
SDK-D03energypublishblockA driver using measure_battery or alarm_battery must declare energy.batteries (array) unless it is a homeBattery or electricCar.source · SDK3
SDK-D04energydebugblockenergy.batteries entries must be known battery types (CR2032, AA, AAA, INTERNAL, OTHER…).source · SDK3
SDK-D05energydebugblockenergy.cumulativeImported/ExportedCapability and meterPowerImported/ExportedCapability may only point at meter_power or meter_power.<sub>.source · SDK3 energy v2
SDK-D06energyprojectreportenergy.approximation values (usageOn/usageOff/usageConstant) should be non-negative numbers in W.source · SDK3
SDK-D07imagespublishblockDriver images.small (75x75) and images.large (500x500) are required at publish with exact size; xlarge is checked by SDK-D20.source · SDK3
SDK-D08driversdebugblockEvery driver id has a matching /drivers/<id> folder (case-sensitive).source · SDK3
SDK-D09capabilitiesdebugblockcapabilitiesOptions.<cap> must be an object.source · SDK3
SDK-D10capabilitiesprojectreportcapabilitiesOptions keys should match a capability the driver actually lists (otherwise the option is dead).source · SDK3
SDK-D11settingsdebugblockDriver 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-D12settingsdebugreportSetting ids should not start with reserved prefixes (homey:, zw_, zb_, mtr_, energy_, zone_…) — Homey warns.source · SDK3
SDK-D13settingsprojectreportSetting ids are unique inside one driver (a duplicate silently shadows the other).source · SDK3
SDK-D14platformsdebugblockA driver may only list platforms the app lists; cloud drivers cannot use lan, matter or rf868 connectivity.source · SDK3
SDK-D15platformsverifiedreportVerified apps need platforms and connectivity on every driver.source · SDK3
SDK-D16zigbeedebugblockZigbee 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-D17zigbeeprojectreportNo duplicated manufacturerName inside one driver (case-insensitive), padded forms kept verbatim.source · project P2941
SDK-D18driversdebugblockdriver.discovery, when a string, must name an entry of app.discovery.source · SDK3
SDK-D19driversdebugblockDriver ids are unique and every driver has a name.en.source · SDK3
SDK-M16imagesprojectreportOptional app images.xlarge (1000x700), when declared, should exist and have the exact size.source · SDK3
SDK-D20imagesprojectreportOptional driver images.xlarge (1000x1000), when declared, should exist and have the exact size.source · SDK3
SDK-D21zigbeeprojectreportA Zigbee driver with an empty manufacturerName or productId list can never match a device during pairing.source · SDK3
SDK-F01flowdebugblockFlow card ids are unique per type (triggers / conditions / actions), driver cards included after compose.source · SDK3
SDK-F02flowdebugblocktitleFormatted (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-F03flowprojectblockAn 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-F04flowverifiedreportCards with arguments need titleFormatted (warning now, required for verified).source · SDK3
SDK-F05flowverifiedreportEvery non-implicit argument has a title (required for verified).source · SDK3
SDK-F06flowdebugblockArgument 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-F07flowdebugblockmultiselect arguments need compatibility >=12.5.0.source · homey-lib (Homey 12.5.0)
SDK-F08flowdebugreportTokens declare a type (boolean, number, string, image); missing type defaults to string and will become mandatory.source · SDK3
SDK-F09flowdebugblockA card platforms list may only contain platforms the app supports.source · SDK3
SDK-F10flowdebugblockEvery card has a string id and a title with an "en" entry.source · SDK3
SDK-P01publishingpublishblock.homeychangelog.json is valid JSON: keys are x.y.z versions, values are i18n objects with an "en" string.source · SDK3
SDK-P02publishingprojectreportThe changelog should have an entry for the current version (Athom shows it as "What's new").source · SDK3
SDK-P03publishingpublishblocknode_modules inside the built app must contain no symbolic links (npm link leftovers).source · SDK3
SDK-P04publishingprojectreportUnofficial: 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-P05publishingprojectreportNEW: .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-P06publishingverifiedreportREADME.txt is plain text, short, without URLs or a changelog.source · Guidelines 1.3

← Knowledge base index · source