Create subitem JSON + new workflows to support rpi-imager 2.0

[billz]

Discussed in #2014

^{Originally posted by @RichardHowells November 25, 2025}

The quick start suggests using one of the prebuilt images, and mentions the need to use Raspberry Pi imager, or similar, to set a user id and password.
I discovered that the 2.0 version does not allow you to do that. I downgraded to the last of the 1.9 versions which does allow setting user id/password before burning the image to the SD card.

Description

While I understand the rationale behind the decision to move rpi-imager in this direction, it does complicate things for custom OS providers in the near term.

Providing a subitem JSON file to include RaspAP in rpi-imager would (re)enable the OS customizations. While it's nice to have a custom entry in rpi-imager, it raises a few concerns:

1. The entry is pinned to a specific release of RaspAP until the next rpi-imager release. Our release cadence is substantially higher than rpi-imager, so our users will be forced to download an old version and update it.
2. Our build generates compressed .img.zip files with sha256 signatures, but not the extract sha256 + sizes. This requires modifying the build to record the uncompressed arm64 + armhf image sizes, and computing their sha256 signatures.
3. It requires a new automated workflow to generate an updated JSON file, and open a PR with rpi-imager after each release.
4. Our torrent files are rendered (mostly) useless. This leaves bandwidth constrained users out in the cold.

The alternative is to ignore rpi-imager completely, and give our users clear instructions to provide their own userconf in the root partition.

[lurch]

1. The entry is pinned to a specific release of RaspAP until the next rpi-imager release. Our release cadence is substantially higher than rpi-imager, so our users will be forced to download an old version and update it.

This is wrong. The way that it works is that https://downloads.raspberrypi.com/os_list_imagingutility_v3.json includes a reference to your sublist JSON file (on your own server). You're then free to modify your sublist JSON file at whatever cadence you desire, and we have an automated task which regularly fetches all the sublist JSON files and "flattens" them into https://downloads.raspberrypi.com/os_list_imagingutility_v4.json
This latter URL is what Imager (both 2.0.x and also 1.9.x) reads every time it starts up.

and open a PR with rpi-imager after each release.

Also not required, see above 🙂

@tdewey_rpi Perhaps it's worth explaining this in https://github.com/raspberrypi/rpi-imager/blob/main/doc/schema-notes.md or https://github.com/raspberrypi/rpi-imager/blob/main/README.md to prevent similar misunderstandings in future?

[billz]

@lurch thanks for pointing this out :)

This became clear after looking at os_list_imagingutility_v3.json. It wasn't obvious from the schema notes or README how this was used. The process of manually submitting our project details and JSON file via a web form seemed to suggest it would live in the rpi-imager repo, rather than storing a pointer to it. Now I gather this is strictly for quality control. Cheers