{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://widget.cdn.septima.dk/3.24.1/schema/widget.schema.json",
  "title": "Septima Widget Configuration",
  "description": "Root object of a Septima Widget JSON configuration file. Either 'map' or 'data' defines the primary context of the widget. 'map' is for map-based widgets, while 'data' is for non-map widgets that still use layers and controls.",
  "type": "object",
  "additionalProperties": false,

  "patternProperties": {
    "^__": {
      "description": "Prefix a property name with \"__\" to comment it out. Such properties are always allowed."
    }
  },

  "properties": {

    "map": {
      "$ref": "./components/map.schema.json",
      "description": "Defines a widget with a visible map. Mutually exclusive with 'data' at the root level."
    },

    "data": {
      "$ref": "./components/data.schema.json",
      "description": "Defines a data-only widget (no map). Loads vector layers and controls without rendering a map. Mutually exclusive with 'map' at the root level."
    },

    "title": {
      "type": "string",
      "description": "Widget title. Displayed to screen readers in the browser title."
    },

    "id": {
      "type": ["number", "string"],
      "description": "Widget identifier. Matches the 'data-widget' attribute on the HTML element when a single configuration file is shared across multiple widgets."
    },

    "debug": {
      "oneOf": [
        { "type": "boolean" },
        { "type": "string", "enum": ["log", "info", "warn", "error"], "description": "A single log level to enable." },
        { "type": "array", "items": { "type": "string", "enum": ["log", "info", "warn", "error"] }, "description": "Multiple log levels to enable." }
      ],
      "default": false,
      "description": "Output diagnostic information to the browser developer console. Set to true to enable all logging, or pass a log level string (or array of strings) to enable specific channels. Can also be enabled via the data-widget-debug HTML attribute or the widget-debug URL parameter."
    },

    "locale": {
      "type": "string",
      "default": "da-DK",
      "description": "Language code for built-in UI texts. Can also be set via the data-widget-locale HTML attribute.",
      "examples": ["da-DK", "en-US"]
    },

    "css": {
      "oneOf": [
        { "type": "string" },
        { "type": "array", "items": { "type": "string" } }
      ],
      "description": "URL or list of URLs to additional CSS files loaded alongside the widget."
    },

    "cssProperties": {
      "type": "object",
      "description": "CSS custom property (variable) overrides, e.g. { \"--sw-map-height\": \"100dvh\" }. Applied to the html element by default, see cssPropertiesTarget.",
      "additionalProperties": { "type": "string" }
    },

    "cssPropertiesTarget": {
      "type": "string",
      "enum": ["root", "container"],
      "default": "root",
      "description": "Where cssProperties are set. \"root\" (default) sets them on the html element, so variables derived from the overridden ones (e.g. --sw-card-title-color from --sw-primary) follow along. The values then apply to the whole page and to all widgets on it. \"container\" sets them on the widget container, so each widget can have its own theme, but derived variables do not follow along."
    },

    "preloadJSON": {
      "type": "array",
      "description": "List of JSON file URLs to pre-fetch before the widget initialises. The fetched data is cached and reused when referenced in layer or control configurations.",
      "items": { "type": "string" }
    },

    "metadata": {
      "type": "object",
      "description": "Free-form metadata about the widget itself. Not used by the widget at runtime - available for external tooling/cataloguing. Can contain any property.",
      "additionalProperties": true,
      "properties": {
        "title": {
          "type": "string",
          "description": "Human-readable title of the widget."
        },
        "description": {
          "type": "string",
          "description": "Human-readable description of the widget."
        },
        "tags": {
          "type": "array",
          "description": "Free-form tags for categorising or searching for the widget.",
          "items": { "type": "string" }
        }
      }
    }
    
  }
}