Appendix 2: Settings File Schema

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
        "format_version": {
            "type": "number",
            "const": 1,
            "description": "Settings file format version"
        },
        "version": {
            "type": "integer",
            "minimum": 1,
            "description": "Settings schema version (bump to discard previously stored values)"
        },
        "fields": {
            "$ref": "#/$defs/fields",
            "description": "List of settings entries"
        }
    },
    "required": [
        "format_version",
        "version",
        "fields"
    ],
    "$defs": {
        "fields": {
            "type": "object",
            "minProperties": 1,
            "propertyNames": {
                "pattern": "^[a-z][a-z0-9_]*$"
            },
            "additionalProperties": {
                "$ref": "#/$defs/node"
            },
            "description": "Map of settings entries, keyed by the entry ID (must be unique on the same level)"
        },
        "node": {
            "type": "object",
            "properties": {
                "type": {
                    "enum": ["boolean", "integer", "string", "enum", "color", "time", "geolocation", "group"],
                    "description": "Entry type"
                },
                "label": {
                    "type": "string",
                    "description": "Display name to be shown in the UI"
                },
                "description": {
                    "type": "string",
                    "description": "Help text to be shown in the UI"
                }
            },
            "required": [
                "type",
                "label"
            ],
            "oneOf": [
                { "$ref": "#/$defs/boolean" },
                { "$ref": "#/$defs/integer" },
                { "$ref": "#/$defs/string" },
                { "$ref": "#/$defs/enum" },
                { "$ref": "#/$defs/color" },
                { "$ref": "#/$defs/time" },
                { "$ref": "#/$defs/geolocation" },
                { "$ref": "#/$defs/group" }
            ]
        },
        "boolean": {
            "properties": {
                "type": { "const": "boolean" },
                "default": {
                    "type": "boolean",
                    "description": "Default value"
                }
            },
            "required": ["default"]
        },
        "integer": {
            "properties": {
                "type": { "const": "integer" },
                "default": {
                    "type": "integer",
                    "minimum": -2147483648,
                    "maximum": 2147483647,
                    "description": "Default value (must be within [min, max])"
                },
                "min": {
                    "type": "integer",
                    "minimum": -2147483648,
                    "maximum": 2147483647,
                    "default": -2147483648,
                    "description": "Minimum allowed value, inclusive (must not exceed max)"
                },
                "max": {
                    "type": "integer",
                    "minimum": -2147483648,
                    "maximum": 2147483647,
                    "default": 2147483647,
                    "description": "Maximum allowed value, inclusive"
                },
                "step": {
                    "type": "integer",
                    "minimum": 1,
                    "default": 1,
                    "description": "Value increment in the UI (max - min must be evenly divisible by step)"
                }
            },
            "required": ["default"]
        },
        "string": {
            "properties": {
                "type": { "const": "string" },
                "default": {
                    "type": "string",
                    "description": "Default value (length must be within [min_length, max_length])"
                },
                "min_length": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 255,
                    "default": 0,
                    "description": "Minimum value length in bytes (must not exceed max_length)"
                },
                "max_length": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 255,
                    "default": 64,
                    "description": "Maximum value length in bytes"
                },
                "sensitive": {
                    "type": "boolean",
                    "default": false,
                    "description": "If true, mask the value in the UI"
                }
            },
            "required": ["default"]
        },
        "enum": {
            "properties": {
                "type": { "const": "enum" },
                "default": {
                    "type": "string",
                    "description": "Default value (must match one of the option values)"
                },
                "options": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 32,
                    "items": {
                        "type": "object",
                        "properties": {
                            "value": {
                                "type": "string",
                                "description": "Option value to be stored (must be unique within the options)"
                            },
                            "label": {
                                "type": "string",
                                "description": "Option name to be shown in the UI"
                            }
                        },
                        "required": ["value", "label"]
                    },
                    "description": "List of available options"
                }
            },
            "required": ["default", "options"]
        },
        "color": {
            "properties": {
                "type": { "const": "color" },
                "default": {
                    "type": "string",
                    "pattern": "^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$",
                    "description": "Default value in #RRGGBB or #RRGGBBAA format (#RRGGBB is fully opaque)"
                }
            },
            "required": ["default"]
        },
        "time": {
            "properties": {
                "type": { "const": "time" },
                "default": {
                    "type": "string",
                    "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$",
                    "description": "Default value in HH:MM or HH:MM:SS format"
                }
            },
            "required": ["default"]
        },
        "geolocation": {
            "properties": {
                "type": { "const": "geolocation" },
                "default": {
                    "type": "object",
                    "properties": {
                        "mode": {
                            "enum": ["auto", "fixed"],
                            "description": "Location source: determined by the device (auto) or explicit coordinates (fixed)"
                        },
                        "name": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 128,
                            "description": "Location name to be shown in the UI (1 to 128 bytes)"
                        },
                        "lat": {
                            "type": "number",
                            "minimum": -90,
                            "maximum": 90,
                            "description": "Latitude in degrees (fixed mode only)"
                        },
                        "lon": {
                            "type": "number",
                            "minimum": -180,
                            "maximum": 180,
                            "description": "Longitude in degrees (fixed mode only)"
                        }
                    },
                    "required": ["mode", "name"],
                    "oneOf": [
                        {
                            "properties": { "mode": { "const": "auto" } },
                            "not": { "anyOf": [{ "required": ["lat"] }, { "required": ["lon"] }] }
                        },
                        {
                            "properties": { "mode": { "const": "fixed" } },
                            "required": ["lat", "lon"]
                        }
                    ],
                    "description": "Default value"
                }
            },
            "required": ["default"]
        },
        "group": {
            "properties": {
                "type": { "const": "group" },
                "fields": {
                    "$ref": "#/$defs/fields",
                    "description": "List of nested settings entries (groups can be nested up to 4 levels deep)"
                }
            },
            "required": ["fields"]
        }
    }
}