relevant_systems.json — bundled systems contract

This page defines the contract for relevant_systems.json, used to declare other systems that can be installed alongside the current template.

Purpose

• Lists bundled systems that are relevant to install with the current system.
• Powers a modal where users choose which bundled systems to include.
• Uses unique_id for consistent retrieval via the backend instead of paths or download URLs.

Location

• Place relevant_systems.json at the zip root next to metadata.json.
• It does not enumerate items under Optionals/ (those are handled separately by their own metadata.json).

Schema

[
  {
    "display_name": "Human-readable name",
    "unique_id": "uuid-from-marketplace-registry",
    "always_on": true,
    "isInitiallyChecked": true
  }
]

• display_name (string): User-facing name for the bundled system.
• unique_id (string): The globally unique ID from the marketplace registry (template_retrieval.TRF_metadata).
• always_on (boolean): If true, this entry is required and cannot be unchecked. Required systems are installed before proceeding with the originally requested system.
• isInitiallyChecked (boolean): If true, checked by default unless always_on.

Example

[
  {
    "display_name": "Inventory Core",
    "unique_id": "a2b4c6d8-e0f2-4a6c-9b8d-1234567890ab",
    "always_on": true,
    "isInitiallyChecked": true
  },
  {
    "display_name": "Economy Basics",
    "unique_id": "c0ffee00-0000-4000-8000-0000c0ffee00",
    "always_on": false,
    "isInitiallyChecked": true
  },
  {
    "display_name": "Vehicles Extension",
    "unique_id": "deadbeef-dead-beef-dead-beefdeadbeef",
    "always_on": false,
    "isInitiallyChecked": false
  }
]

How it works (what you’ll see)

• When a template includes relevant_systems.json, the app shows a "Relevant systems" modal before installing. You can choose which related systems to include. Entries marked always_on are required and locked on.
• You don’t need links or paths in this file; the app handles downloads and installation for you.

Required systems and follow-ups

• If any required (always_on) system isn’t installed yet, you’ll see a notice: required systems will be installed first. Click "Continue" and the app will take care of it automatically. If they’re already installed, it proceeds normally.
• If you check optional systems in the modal, after finishing the current install the app will ask: "Do you want me to install the N selected systems next?" Choose Yes to continue with those installs.

Authoring guidelines

• Prefer concise display_name values.
• Only include truly relevant systems; keep the list short.
• Ensure each unique_id corresponds to a valid marketplace entry.
• Avoid duplicates; if two entries refer to the same unique_id, keep one.

Validation checklist

• File is valid JSON array.
• Each entry has a display_name and unique_id string.
• Optional booleans are correctly typed (always_on, isInitiallyChecked).
• No legacy path or download_url fields are present.