New configuration schema for Launch Manager

src/launch_manager_daemon/config/future_config_schema/README.rst

@@ -0,0 +1,173 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2026 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
+
+Launch Manager Configuration Schema
+###################################
+
+This folder contains the development environment for the Launch Manager configuration JSON Schema. The schema defines and validates the structure of Launch Manager configuration files.
+
+Overview
+********
+
+This project uses a **two-folder approach** for schema management:
+
+- ``draft_schema/`` - Multi-file schema structure for active development
+- ``published_schema/`` - Single-file schema for end-user consumption
+
+The multi-file structure in ``draft_schema/`` makes it easier to maintain and modify the schema by organizing reusable components into separate files. When development is complete, these files are compiled into a single file in ``published_schema/`` for convenience of end users.
+
+**Project Structure:**
+
+::
+
+    +-- draft_schema/          # Multi-file schema under development
+    +-- published_schema/      # Single-file schema ready for use
+    +-- examples/              # Sample configuration files
+    +-- scripts/               # Tools for bundling and validation
+
+Quick Start
+***********
+
+For End Users
+=============
+
+If you just want to validate your Launch Manager configuration:
+
+1. Use the schema in ``published_schema/s-core_launch_manager.schema.json``
+2. Check the ``examples/`` folder for sample configurations
+3. Validate your config:
+
+   .. code-block:: bash
+
+      validate.py --schema published_schema/s-core_launch_manager.schema.json --instance your_config.json
+
+For Schema Developers
+======================
+
+If you're modifying or extending the schema:
+
+1. Edit files in ``draft_schema/``
+2. Bundle your changes:
+
+   .. code-block:: bash
+
+      bundle.py --input draft_schema/s-core_launch_manager.schema.json --output published_schema/s-core_launch_manager.schema.json
+
+3. Test against examples to ensure nothing broke
+
+
+Examples
+********
+
+Configuration examples are provided in the ``examples`` folder, each accompanied by a brief description. **Start here** if you're new to Launch Manager configurations - these show real-world usage patterns.
+
+
+Schema Development (draft_schema)
+**********************************
+
+The ``draft_schema`` folder contains the primary development work. The setup uses a multi-file structure where:
+
+- **Reusable types** are stored in the ``types/`` subfolder
+- **Top-level schema** resides in ``s-core_launch_manager.schema.json`` file
+
+Working with $ref Paths
+========================
+
+The multi-file schema uses JSON Schema's ``$ref`` keyword to reference definitions across files. Understanding how these references work is crucial when modifying the schema.
+
+**Key principle:** All ``$ref`` paths are relative to the location of the file containing the reference, not to any root folder.
+
+Reference Examples
+------------------
+
+**To reference a file in a subfolder** (e.g., from ``s-core_launch_manager.schema.json`` to ``types/deployment_config.schema.json``):
+
+.. code-block:: json
+
+    "$ref": "./types/deployment_config.schema.json"
+
+**To reference a file in the same folder:** (e.g., from ``types/deployment_config.schema.json`` to ``types/recovery_action.schema.json``):
+
+.. code-block:: json
+
+    "$ref": "./recovery_action.schema.json"
+
+Common Pitfalls
+---------------
+
+- **Always use relative paths** starting with ``./`` or ``../``
+- **Don't use absolute paths** or paths from the project root
+- **Remember the current file's location** when constructing paths
+- When moving files, **update all references** to and from that file
+
+The bundling script resolves all these relative references into a single file, so the published schema doesn't need external file references.
+
+
+Published Schema (published_schema)
+************************************
+
+The official, end-user consumable schema is placed in the ``published_schema`` folder. Upon completion of development, the multi-file schema from the ``draft_schema`` folder is merged into a single file and published here.
+
+**This is the version end users should reference** in their validation tools and IDE configurations.
+
+
+Scripts
+*******
+
+Utility scripts for schema development are located in the ``scripts`` folder:
+
+bundle.py
+=========
+
+Merges the multi-file schema into a single file for end-user distribution.
+
+**Usage:**
+
+.. code-block:: bash
+
+   bundle.py --input ../draft_schema/s-core_launch_manager.schema.json --output ../published_schema/s-core_launch_manager.schema.json 
+   Bundled schema written to: ../published_schema/s-core_launch_manager.schema.json
+
+**When to use:** After making changes in ``draft_schema/``, run this to create the publishable version.
+
+validate.py
+===========
+
+Validates Launch Manager configuration instances against the schema. This script supports both single-file and multi-file schema formats.
+
+**Validate against published schema:**
+
+.. code-block:: bash
+
+   validate.py --schema ../published_schema/s-core_launch_manager.schema.json --instance ../examples/example_conf.json 
+   Success --> ../examples/example_conf.json: valid
+
+**Validate against draft schema (during development):**
+
+.. code-block:: bash
+
+   validate.py --schema ../draft_schema/s-core_launch_manager.schema.json --instance ../examples/example_conf.json 
+   Success --> ../examples/example_conf.json: valid
+
+**When to use:** Run this frequently during development to catch errors early. Always validate examples before publishing.
+
+
+Typical Workflow
+****************
+
+1. **Modify** schema files in ``draft_schema/``
+2. **Validate** your changes against examples using the draft schema
+3. **Bundle** the multi-file schema into a single file
+4. **Validate** examples again against the published schema

src/launch_manager_daemon/config/future_config_schema/draft_schema/s-core_launch_manager.schema.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "title": "Configuration schema for the S-CORE Launch Manager",
+  "description": "Defines the structure and valid values for the Launch Manager configuration file, which specifies managed components, run targets, and recovery behaviors.",
+  "properties": {
+    "schema_version": {
+      "type": "integer",
+      "description": "Specifies the schema version number that the Launch Manager uses to determine how to parse and validate this configuration file.",
+      "enum": [ 1 ]
+    },
+    "defaults": {
+      "type": "object",
+      "description": "Defines default configuration values that components and Run Targets inherit unless they provide their own overriding values.",
+      "properties": {
+        "component_properties": {
+          "$ref": "./types/component_properties.schema.json",
+          "description": "Defines default component property values applied to all components unless overridden in individual component definitions."
+        },
+        "deployment_config": {
+          "$ref": "./types/deployment_config.schema.json",
+          "description": "Defines default deployment configuration values applied to all components unless overridden in individual component definitions."
+        },
+        "run_target": {
+          "$ref": "./types/run_target.schema.json",
+          "description": "Defines default Run Target configuration values applied to all Run Targets unless overridden in individual Run Target definitions."
+        },
+        "alive_supervision": {
+          "$ref": "./types/alive_supervision.schema.json",
+          "description": "Defines default alive supervision configuration values used unless a global 'alive_supervision' configuration is specified at the root level."
+        },
+        "watchdog": {
+          "$ref": "./types/watchdog.schema.json",
+          "description": "Defines default watchdog configuration values applied to all watchdogs unless overridden in individual watchdog definitions."
+        }
+      },
+      "required": [],
+      "additionalProperties": false
+    },
+    "components": {
+      "type": "object",
+      "description": "Defines software components managed by the Launch Manager, where each property name is a unique component identifier and its value contains the component's configuration.",
+      "patternProperties": {
+        "^[a-zA-Z0-9_-]+$": {
+          "type": "object",
+          "description": "Defines an individual component's configuration properties and deployment settings.",
+          "properties": {
+            "description": {
+              "type": "string",
+              "description": "Specifies a human-readable description of the component's purpose."
+            },
+            "component_properties": {
+              "$ref": "./types/component_properties.schema.json",
+              "description": "Defines component properties for this component; any properties not specified here are inherited from 'defaults.component_properties'."
+            },
+            "deployment_config": {
+              "$ref": "./types/deployment_config.schema.json",
+              "description": "Defines deployment configuration for this component; any properties not specified here are inherited from 'defaults.deployment_config'."
+            }
+          },
+          "required": [],
+          "additionalProperties": false
+        }
+      },
+      "required": [],
+      "additionalProperties": false
+    },
+    "run_targets": {
+      "type": "object",
+      "description": "Defines Run Targets representing different operational modes of the system, where each property name is a unique Run Target identifier and its value contains the Run Target's configuration.",
+      "patternProperties": {
+        "^[a-zA-Z0-9_-]+$": {
+          "$ref": "./types/run_target.schema.json"
+        }
+      },
+      "required": [],
+      "additionalProperties": false
+    },
+    "initial_run_target": {
+      "type": "string",
+      "description": "Specifies the name of the initial Run Target that the Launch Manager activates during the startup sequence. This name must match a Run Target defined in 'run_targets'."
+    },
+    "fallback_run_target": {
+      "type": "object",
+      "description": "Defines the fallback Run Target configuration that the Launch Manager activates when all recovery attempts have been exhausted. This Run Target does not include a recovery_action property.",
+      "properties": {
+        "description": {
+          "type": "string",
+          "description": "Specifies a human-readable description of the fallback Run Target."
+        },
+        "depends_on": {
+          "type": "array",
+          "description": "Specifies the names of components and Run Targets that must be activated when this Run Target is activated.",
+          "items": {
+            "type": "string",
+            "description": "Specifies the name of a component or Run Target that this Run Target depends on."
+          }
+        },
+        "transition_timeout": {
+          "type": "number",
+          "description": "Specifies the time limit, in seconds (e.g., '1.5' for 1500 milliseconds), for the Run Target transition. If this limit is exceeded, the transition is considered failed.",
+          "exclusiveMinimum": 0
+        }
+      },
+      "required": [
+        "depends_on"
+      ],
+      "additionalProperties": false
+    },
+    "alive_supervision": {
+      "$ref": "./types/alive_supervision.schema.json",
+      "description": "Defines the alive supervision configuration parameters used to monitor component health. This configuration overrides 'defaults.alive_supervision' if specified."
+    },
+    "watchdog": {
+      "$ref": "./types/watchdog.schema.json",
+      "description": "Defines the external watchdog device configuration used by the Launch Manager. This configuration overrides 'defaults.watchdog' if specified."
+    }
+  },
+  "required": [
+    "schema_version",
+    "initial_run_target"
+  ],
+  "additionalProperties": false
+}

src/launch_manager_daemon/config/future_config_schema/draft_schema/types/alive_supervision.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "description": "Defines a reusable type that contains configuration parameters for alive supervision.",
+  "properties": {
+    "evaluation_cycle": {
+      "type": "number",
+      "exclusiveMinimum": 0,
+      "description": "Specifies the length, in seconds (e.g., '0.5' for 500 milliseconds), of the time window used to assess incoming alive supervision reports."
+    }
+  },
+
+  "required": [],
+  "additionalProperties": false
+}