{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "ViewDefinition.schema.json",
  "title": "ViewDefinition",
  "x-group": "Definitions",
  "type": "object",
  "description": "A declarative UI definition structure for building dynamic, data-driven layouts.\n\n`ViewDefinition` provides a flexible, JSON-serializable way to define user interface layouts\nthat can be rendered dynamically at runtime. It's designed for building data-driven UIs,\nserver-driven rendering, or any scenario where UI structure needs to be defined outside of code.",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for this view definition.\n\nAutomatically generated UUID string."
    },
    "title": {
      "type": "string",
      "description": "The title or name of this layout.\n\nUsed for documentation, debugging, or display in development tools."
    },
    "type": {
      "$ref": "#/$defs/LayoutType",
      "description": "Determines how child views are arranged.\n\n- SeeAlso: `LayoutType`"
    },
    "alignment": {
      "$ref": "#/$defs/Alignment",
      "description": "- SeeAlso: `Alignment`"
    },
    "spacing": {
      "type": "number",
      "description": "Spacing between root-level views in points."
    },
    "padding": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Padding around the entire layout.\n\nCan specify:\n- Single value: `[20]` - all sides\n- Two values: `[16, 20]` - vertical, horizontal\n- Three values: `[16, 20, 24]` - top, horizontal, bottom\n- Four values: `[10, 15, 20, 15]` - top, right, bottom, left"
    },
    "bgColor": {
      "type": "string",
      "description": "Background color for the entire layout."
    },
    "bgImage": {
      "type": "string",
      "description": "Background image path for the entire layout."
    },
    "width": {
      "type": "number",
      "description": "Fixed width for the layout in points."
    },
    "height": {
      "type": "number",
      "description": "Fixed height for the layout in points."
    },
    "frame": {
      "$ref": "#/$defs/Frame",
      "description": "Frame constraints for the entire layout.\n\n- SeeAlso: `Frame`"
    },
    "custom": {
      "type": "object",
      "additionalProperties": true,
      "description": "Custom properties for extension and specialized behavior.\n\nAllows passing arbitrary configuration data."
    },
    "views": {
      "type": "array",
      "items": {
        "$ref": "#"
      },
      "description": "The main content views to render.\n\nThese views are rendered in the foreground according to the `type` layout."
    },
    "bgViews": {
      "type": "array",
      "items": {
        "$ref": "#"
      },
      "description": "Background views rendered behind the main content.\n\nUseful for creating layered effects, background images, or decorative elements."
    },
    "debug": {
      "type": "boolean",
      "description": "Enable debug mode for development and troubleshooting.\n\nWhen `true`, may display:\n- View boundaries\n- Layout guides\n- Data binding information\n- Performance metrics"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$defs": {
    "LayoutType": {
      "title": "LayoutType",
      "description": "The type of layout container for arranging child views.\n\nLayout types determine how child views are arranged and displayed within\nthe view definition.",
      "type": "string",
      "enum": [
        "vStack",
        "zStack",
        "lazyVStack",
        "tabs",
        "compactTabs"
      ]
    },
    "Alignment": {
      "title": "Alignment",
      "description": "Content alignment options for views within their container.\n\nAlignment determines how content is positioned within its allocated space.",
      "type": "string",
      "enum": [
        "topLeading",
        "top",
        "topTrailing",
        "leading",
        "center",
        "trailing",
        "bottomLeading",
        "bottom",
        "bottomTrailing"
      ]
    },
    "ImageResizeMode": {
      "title": "ImageResizeMode",
      "description": "How images should be scaled and fitted within their bounds.\n\nImage resize modes control how image content fills or fits its container.",
      "type": "string",
      "enum": [
        "stretch",
        "aspectFit",
        "aspectFill",
        "tile",
        "none"
      ]
    },
    "Frame": {
      "title": "Frame",
      "type": "object",
      "description": "Layout constraints and sizing information for a view.\n\n`Frame` provides fine-grained control over view dimensions, constraints,\nand layout behavior.",
      "properties": {
        "width": {
          "type": "number",
          "description": "Fixed width in points.\n\nWhen set, the view will have exactly this width."
        },
        "height": {
          "type": "number",
          "description": "Fixed height in points.\n\nWhen set, the view will have exactly this height."
        },
        "minWidth": {
          "type": "number",
          "description": "Minimum width constraint in points.\n\nThe view will never be smaller than this width."
        },
        "maxWidth": {
          "type": "number",
          "description": "Maximum width constraint in points.\n\nThe view will never be larger than this width."
        },
        "minHeight": {
          "type": "number",
          "description": "Minimum height constraint in points.\n\nThe view will never be smaller than this height."
        },
        "maxHeight": {
          "type": "number",
          "description": "Maximum height constraint in points.\n\nThe view will never be larger than this height."
        },
        "aspectFit": {
          "type": "number",
          "description": "Aspect ratio for fitting content (width / height).\n\nWhen set, the view maintains this aspect ratio while fitting within constraints."
        },
        "aspectFill": {
          "type": "number",
          "description": "Aspect ratio for filling content (width / height).\n\nWhen set, the view maintains this aspect ratio while filling its container."
        },
        "layoutPriority": {
          "type": "number",
          "description": "Layout priority for resolving conflicts.\n\nHigher values mean the view is less flexible. Used when multiple\nviews compete for space."
        }
      },
      "additionalProperties": false
    },
    "View": {
      "title": "View",
      "type": "object",
      "description": "A single view component within a view definition.\n\n`View` represents an individual UI element that can be rendered. Views can be\nnested to create complex layouts, bound to data, styled, and configured with\nconditional visibility.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for this view.\n\nAutomatically generated UUID string. Used for tracking, animations,\nand list identification."
        },
        "title": {
          "type": "string",
          "description": "The title or label for this view.\nUsed as:\n- Label text\n- Tab titles\n- Button text"
        },
        "value": {
          "type": "string",
          "description": "Static value or template string for this view.\n\nThe interpretation depends on `type`:\n- For `.text`: The text to display\n- For `.image`: The image path or URL"
        },
        "type": {
          "$ref": "#/$defs/ViewType",
          "description": "Determines how this view is displayed and what properties are relevant.\n\n- SeeAlso: `ViewType`"
        },
        "attribute": {
          "type": "string",
          "description": "Data binding path for dynamic content.\n\nSpecifies which property from the data context to display or bind to.\nUses dot notation to access nested properties.\n\n## Example\n```json\n// Simple property\n\"attribute\": \"data.level\"\n\n// Nested property\n\"attribute: \"data.character.abilities.strength\"\n```"
        },
        "attributeType": {
          "type": "string",
          "description": "SystemType or Entity for the attribute value.\n\nHelps renderers format and validate data appropriately."
        },
        "context": {
          "$ref": "#/$defs/ContextType",
          "description": "The data context scope for attribute resolution.\n\n- SeeAlso: `ContextType`"
        },
        "style": {
          "type": "string",
          "description": "Style identifier for this view.\n\nReferences a theme style definition that controls typography, colors,\nspacing, and other visual properties."
        },
        "link": {
          "type": "string",
          "description": "Navigation link\n\nWhen tapped, navigates to the specified destination."
        },
        "alignment": {
          "$ref": "#/$defs/Alignment",
          "description": "Content alignment within this view's bounds.\n\n- SeeAlso: `Alignment`"
        },
        "spacing": {
          "type": "number",
          "description": "Spacing between child views in points.\n\nOnly relevant for stack layouts (vStack, hStack, etc.)."
        },
        "padding": {
          "type": "array",
          "items": {
            "type": "number"
          },
          "description": "Padding around the view's content.\n\nCan specify:\n- Single value: `[20]` - all sides\n- Two values: `[16, 20]` - vertical, horizontal\n- Three values: `[16, 20, 24]` - top, horizontal, bottom\n- Four values: `[10, 15, 20, 15]` - top, right, bottom, left"
        },
        "color": {
          "type": "string",
          "description": "Text or foreground color.\n\nSupports hex colors"
        },
        "bgColor": {
          "type": "string",
          "description": "Background color.\n\nSupports hex colors"
        },
        "bgImage": {
          "type": "string",
          "description": "Background image path"
        },
        "borderWidth": {
          "type": "number",
          "description": "Draws a border of this thickness around the view."
        },
        "borderColor": {
          "type": "string",
          "description": "Border color."
        },
        "borderEdges": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Which edges should display the border.\n\nArray of edge identifiers: `\"top\"`, `\"right\"`, `\"bottom\"`, `\"left\"`."
        },
        "cornerRadius": {
          "type": "number",
          "description": "Corner radius in points for rounded corners."
        },
        "imageResizeMode": {
          "$ref": "#/$defs/ImageResizeMode",
          "description": "How images should be scaled within this view.\n\nOnly relevant for image-based views.\n\n- SeeAlso: `ImageResizeMode`"
        },
        "width": {
          "type": "number",
          "description": "Fixed width in points.\n\nOverrides the default width calculation."
        },
        "height": {
          "type": "number",
          "description": "Fixed height in points.\n\nOverrides the default height calculation."
        },
        "frame": {
          "$ref": "#/$defs/Frame",
          "description": "Frame constraints for this view.\n\nProvides fine-grained control over sizing and layout behavior.\n\n- SeeAlso: `Frame`"
        },
        "visibleIf": {
          "type": "string",
          "description": "Condition for visibility - view shown when this evaluates to true.\n\nExpression string evaluated against the data context.\n\n## Example\n```json\n\"visibleIf\": \"data.hp > 0\"\n\"visibleIf\": \"data.level >= 5\"\n\"visibleIf\": \"data.equipment.count > 0\"\n```"
        },
        "hiddenIf": {
          "type": "string",
          "description": "Condition for hiding - view hidden when this evaluates to true.\n\nExpression string evaluated against the data context.\n\n## Example\n```json\n\"hiddenIf\": \"data.isGM == false\"\n\"hiddenIf\": \"data.inventory.length == 0\"\n```"
        },
        "custom": {
          "type": "object",
          "additionalProperties": true,
          "description": "Custom properties for extension and specialized rendering.\n\nAllows passing arbitrary configuration data to custom renderers\nor view types."
        },
        "action": {
          "type": "object",
          "additionalProperties": true,
          "description": "Action configuration for interactive views.\n\nDefines what happens when the view is interacted with (tapped, submitted, etc.)."
        },
        "views": {
          "type": "array",
          "items": {
            "$ref": "#"
          },
          "description": "Child views nested within this view.\n\nForms a tree structure for complex layouts."
        }
      },
      "required": [
        "id"
      ],
      "additionalProperties": false
    },
    "ViewType": {
      "title": "ViewType",
      "description": "The type of UI component to render.\n\nView types are categorized into layout containers, content elements,\ninteractive controls, and specialized components.",
      "type": "string",
      "enum": [
        "vStack",
        "hStack",
        "zStack",
        "lazyVStack",
        "flow",
        "scroll",
        "list",
        "divider",
        "spacer",
        "text",
        "label",
        "tags",
        "image",
        "icon",
        "tabs",
        "partial",
        "button",
        "buttonGroup",
        "menuButton",
        "checkbox",
        "checkboxGroup",
        "progress",
        "disclosureGroup",
        "field",
        "grid",
        "gridRow",
        "table",
        "tableRow",
        "statBlock"
      ]
    },
    "ContextType": {
      "title": "ContextType",
      "description": "The data context scope for this view.\n\nContext type determines where the view looks for data when evaluating\nattribute bindings and visibility conditions.",
      "type": "string",
      "enum": [
        "local",
        "global",
        "mixed"
      ]
    }
  }
}