Edition schema
Reference for edition.json, the data file that defines a brand edition. For the workflow — creating an edition directory, resolving assets, building — see Build a branded edition.
The file is JSON, schema version 1. The build validates the seven sections it owns (names, viewport, seeds, assets, site, license, source), one packaging key and the top-level keys reportServer and apps; inside those, an unknown key is an error. Top-level sections it does not own pass through untouched for external tooling.
Two readers check the file with the same rules: the qbs edition probe, integration/qbs/imports/EditionProbe.qbs, and kiln's reader in libedition. The app list beside the editions, integration/editions/apps.json, belongs to the checkout, not to an edition: see The app list.
Top level
| Field | Type | Required | Rule / fallback |
|---|---|---|---|
schema |
integer | yes | Must be 1 |
id |
string | yes | Must equal the edition directory's name |
reportServer |
https:// origin |
no | The server the apps send diagnostic reports to. No path, no trailing slash, no user information |
apps |
array of app ids | no | The apps the edition ships, each once, each an id of the app list. Absent ships every app. The help of a build holds only the pages of these apps and their reach |
names
| Field | Type | Required | Rule / fallback |
|---|---|---|---|
names.organization |
string | yes | Display form; ™ allowed |
names.organizationAscii |
string, ASCII only | yes | The on-disk identity: every data, config and cache path. Authored, never derived; any byte above 0x7F fails the resolve |
names.domain |
string | yes | Display form |
names.brand |
string | yes | Display form |
names.applicationBase |
string | no | Defaults to names.brand |
names.app |
string | yes | The name pages print as {{ app_name }} |
names.suite |
string | yes | The name pages print as {{ suite_name }} |
Every name is written once, in Unicode normalization form C, with its marks. The readers derive two more forms from it: the HTML form, with each mark as its entity (™ becomes ™), and the plain form, with no mark at all. When the plain form of names.organization is pure ASCII, it must equal names.organizationAscii.
site, license and source
The values that pages print, from the edition, because the in-app help has no site settings.
| Field | Type | Required | Rule / fallback |
|---|---|---|---|
site.url |
https:// origin |
yes | The edition's own site, such as https://octomy.org. The apps link it, and the documentation lives at <site.url>/documentation/ |
license.name |
string | yes | What pages print as {{ license_name }} |
source.url |
https:// address |
no | What pages print as {{ source_url }}. Absent, each sentence that uses it is hidden |
viewport
| Field | Type | Required | Rule / fallback |
|---|---|---|---|
viewport.backgroundBottom |
#rrggbb |
yes | Bottom of the 3D viewport background pair |
viewport.backgroundTop |
#rrggbb |
yes | Top of the pair |
seeds
One entry per application identity. All nine are required: agent, remote, hub, zoo, construct, bahn, singularity, auda, paint.
| Field | Type | Required | Rule / fallback |
|---|---|---|---|
seeds.<app>.seed |
#rrggbb |
yes | The one color the application's whole palette is computed from |
seeds.<app>.background |
#rrggbb |
no | Pins the palette window color; derived from the seed when absent |
assets
Paths are relative, resolved against the edition directory first, then the project root; a miss in both fails the resolve.
| Field | Type | Required | Rule / fallback |
|---|---|---|---|
assets.logo |
relative path | yes | The logo SVG |
assets.watermark |
relative path | yes | The watermark SVG |
assets.window.<app> |
relative path | no | Per-application window icon. An omitted application gets the "NO EDITION" placeholder |
The build binds each asset to a stable resource alias:
assets.logoto:/branding/logo.svgassets.watermarkto:/branding/watermark.svgassets.window.<app>to:/branding/window/<app>.svg
packaging
The fields below are keys of packaging.
| Field | Type | Required | Rule / fallback |
|---|---|---|---|
androidPackagePrefix |
string | no | Has a default, below |
| any other key | — | no | Not read by this build; passes through for packaging tools |
The default of androidPackagePrefix is org.octomy..
The app list
integration/editions/apps.json lists every app, tool, feature and audience that has published pages. Each key is an app id, ^[a-z][a-z0-9-]*$.
| Field | Type | Required | Rule |
|---|---|---|---|
schema |
integer | yes | Must be 1 |
kind |
app, tool, feature or audience |
yes | A feature runs inside one or more apps and has no program of its own. An audience names a group of readers: developers is the one today. Every tool belongs to the developers |
name |
string | yes | The display name, a product name that keeps its spelling in every edition |
icon |
path | yes | An .svg of the icon set under src/libs/libres/resources/icons/ |
line |
string | yes | One sentence about the entry, with no project name |
robot |
boolean | yes | true for an entry that drives or controls a robot. Only the pages of such entries may say "robot" |
contains |
array of ids | no | The apps and features that run inside this app. The reach of an app is the app and everything it contains, followed to the end. A cycle fails |
libraries |
array of library names | for a feature | The libraries that make the feature |
Each of the nine application identities has an entry of kind app. A page names the ids it is for in its sidecar, as global.apps; [] means a page for every app.
The no-edition fallback
A build resolved with project.editionDir:"" compiles the loud fallback: every seed white, both viewport colors #000000, and the :/branding/* aliases bound to a "NO EDITION" placeholder mark. The name fields of the generated header keep their fallback values, so a wrong name does not read as broken and only the colors are loud. The help of such a build prints the neutral words: "the organization", "the application", "the applications".