{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://ilograph.com/schemas/idl-2025-11-03.json",
  "title": "Ilograph Diagram Language (IDL) - November 2025 Version",
  "description": "Schema for Ilograph YAML diagram specifications based on 2025-11-03 spec",
  "type": "object",
  "properties": {
    "resources": {
      "$ref": "#/$defs/resourceArray"
    },
    "perspectives": {
      "$ref": "#/$defs/perspectiveArray"
    },
    "imports": {
      "$ref": "#/$defs/importArray"
    },
    "contexts": {
      "$ref": "#/$defs/contextArray"
    },
    "description": {
      "type": "string",
      "description": "A description of the diagram that appears at the top of the overview page. Has support for markdown, and can contain multiple lines."
    },
    "defaultContextDisplayName": {
      "type": "string",
      "description": "The display name of the default context"
    }
  },
  "$defs": {
    "resourceArray": {
      "type": "array",
      "description": "An array of resources (the resource tree)",
      "items": {
        "$ref": "#/$defs/resource"
      }
    },

    "perspectiveArray": {
      "type": "array",
      "description": "An array of perspectives",
      "items": {
        "$ref": "#/$defs/perspective"
      }
    },

    "importArray": {
      "type": "array",
      "description": "An array of imports",
      "items": {
        "$ref": "#/$defs/import"
      }
    },

    "contextArray": {
      "type": "array",
      "description": "An array of contexts",
      "items": {
        "$ref": "#/$defs/context"
      }
    },

    "resource": {
      "type": "object",
      "description": "Resources are the building blocks of Ilograph diagrams. Resources can appear in multiple perspectives.",
      "required": ["name"],
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the resource. Used as the identifier if id is not provided."
        },
        "id": {
          "type": "string",
          "pattern": "^[^/\\^*\\[\\],^]*$",
          "description": "A substitute identifier for the resource. Cannot contain restricted characters."
        },
        "subtitle": {
          "type": "string",
          "description": "The subtitle of the resource (appears below the resource name)"
        },
        "description": {
          "oneOf": [
            { "type": "string" },
            { "$ref": "#/$defs/descriptionObject" }
          ],
          "description": "The description of the resource. Supports markdown and can contain multiple lines or be defined as key-value pairs."
        },
        "color": {
          "type": "string",
          "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$|^[a-zA-Z]+$",
          "default": "dimgray",
          "description": "Text color. Any X11 color name or hex value like #FF00FF."
        },
        "backgroundColor": {
          "type": "string",
          "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$|^[a-zA-Z]+$",
          "default": "white",
          "description": "Background color. Any X11 color name or hex value like #FF00FF."
        },
        "style": {
          "type": "string",
          "enum": ["default", "plural", "dashed", "outline", "flat"],
          "default": "default",
          "description": "Resource border style. When set to plural, rendered as multiple boxes."
        },
        "abstract": {
          "type": "boolean",
          "default": false,
          "description": "When set to true, other resources may inherit from this resource using instanceOf."
        },
        "instanceOf": {
          "type": "string",
          "description": "When specified, this resource inherits all properties (other than id/name) and child resources of the specified abstract resource."
        },
        "children": {
          "$ref": "#/$defs/resourceArray",
          "description": "An array of child resources"
        },
        "icon": {
          "type": "string",
          "description": "An icon path for the resource"
        },
        "iconStyle": {
          "type": "string",
          "enum": ["default", "silhouette"],
          "default": "default",
          "description": "Controls how the icon is rendered."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "URL for the resource. If defined, a link icon appears when selected."
        },
        "layout": {
          "$ref": "#/$defs/layout"
        }
      },
      "additionalProperties": false
    },

    "descriptionObject": {
      "type": "object",
      "description": "Key-value pair description format"
    },

    "perspective": {
      "type": "object",
      "description": "Each perspective gives a unique view of the relations between resources.",
      "required": ["name"],
      "properties": {
        "id": {
          "type": "string",
          "description": "A substitute identifier for the perspective."
        },
        "name": {
          "type": "string",
          "description": "Name of the perspective. Used as unique identifier if id not provided."
        },
        "color": {
          "type": "string",
          "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$|^[a-zA-Z]+$",
          "default": "royalblue",
          "description": "Color of the perspective. Any X11 color name or hex value."
        },
        "relations": {
          "$ref": "#/$defs/relationArray",
          "description": "An array of relations"
        },
        "sequence": {
          "$ref": "#/$defs/sequence",
          "description": "Sequence object for sequence perspectives"
        },
        "notes": {
          "type": "string",
          "description": "Notes that appear in the notes panel and overview page. Supports markdown."
        },
        "extends": {
          "type": "string",
          "description": "Previously-defined perspective(s) that this perspective extends."
        },
        "walkthrough": {
          "$ref": "#/$defs/slideArray",
          "description": "An array of slides forming the walkthrough"
        },
        "aliases": {
          "$ref": "#/$defs/aliasArray",
          "description": "An array of aliases"
        },
        "overrides": {
          "$ref": "#/$defs/overrideArray",
          "description": "An array of overrides"
        },
        "orientation": {
          "type": "string",
          "enum": ["leftToRight", "topToBottom", "ring"],
          "default": "leftToRight",
          "description": "Which direction the perspective is oriented. Does not affect sequence perspectives."
        },
        "options": {
          "$ref": "#/$defs/perspectiveOptions",
          "description": "Additional options for this perspective"
        }
      },
      "additionalProperties": false,
      "oneOf": [
        {
          "required": ["relations"],
          "description": "Perspectives with relations are relation perspectives"
        },
        {
          "required": ["sequence"],
          "description": "Perspectives with sequence are sequence perspectives"
        }
      ]
    },

    "relationArray": {
      "type": "array",
      "description": "Relations define how resources are related to each other in the perspective.",
      "items": {
        "$ref": "#/$defs/relation"
      }
    },

    "relation": {
      "type": "object",
      "description": "Relations define how resources are related to each other in the perspective. Each relation must define from or to.",
      "properties": {
        "from": {
          "type": "string",
          "description": "Reference(s) to the dependent (left-side) resource(s)"
        },
        "to": {
          "type": "string",
          "description": "Reference(s) to the independent (right-side) resource(s)"
        },
        "via": {
          "type": "string",
          "description": "Reference(s) to resource(s) this relation passes through"
        },
        "label": {
          "type": "string",
          "description": "Label that appears above the arrow(s)"
        },
        "description": {
          "type": "string",
          "description": "Extended description for hover text. Supports markdown."
        },
        "arrowDirection": {
          "type": "string",
          "enum": ["forward", "backward", "bidirectional"],
          "default": "forward",
          "description": "Arrow direction relative to perspective orientation."
        },
        "color": {
          "type": "string",
          "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$|^[a-zA-Z]+$",
          "default": "#303030",
          "description": "Arrow and text color. Any X11 color name or hex value."
        },
        "secondary": {
          "type": "boolean",
          "default": false,
          "description": "If true, relation will not affect perspective layout. Does not affect ring perspectives."
        }
      },
      "oneOf": [{ "required": ["from"] }, { "required": ["to"] }],
      "additionalProperties": false
    },

    "sequence": {
      "type": "object",
      "description": "Sequence defines how resources are related in a sequence of steps.",
      "required": ["start"],
      "properties": {
        "start": {
          "type": "string",
          "description": "Starting resource in the sequence, or none to have first step come from off-screen"
        },
        "steps": {
          "$ref": "#/$defs/stepArray",
          "description": "An array of steps in the sequence"
        }
      },
      "additionalProperties": false
    },

    "stepArray": {
      "type": "array",
      "description": "Steps in a sequence define the steps between resources and their labels.",
      "items": {
        "$ref": "#/$defs/step"
      }
    },

    "step": {
      "type": "object",
      "description": "Steps in a sequence define the steps between resources and their labels. Each step must define to, toAndBack, toAsync, restartAt, or subSequence.",
      "properties": {
        "to": {
          "type": "string",
          "description": "Resource this step goes to"
        },
        "toAndBack": {
          "type": "string",
          "description": "Resource this step goes to with automatic return"
        },
        "toAsync": {
          "type": "string",
          "description": "Resource this step goes to asynchronously (drawn with dashed arrows)"
        },
        "restartAt": {
          "type": "string",
          "description": "Resource to pass control to without drawing an arrow"
        },
        "subSequence": {
          "$ref": "#/$defs/subSequence",
          "description": "A sub-sequence object"
        },
        "label": {
          "type": "string",
          "description": "Label that appears above the arrow"
        },
        "description": {
          "type": "string",
          "description": "Extended description for hover text. Supports markdown."
        },
        "bidirectional": {
          "type": "boolean",
          "default": false,
          "description": "If true, arrows are shown with arrowheads on both ends."
        },
        "color": {
          "type": "string",
          "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$|^[a-zA-Z]+$",
          "default": "#303030",
          "description": "Arrow and text color. Any X11 color name or hex value."
        }
      },
      "oneOf": [
        { "required": ["to"] },
        { "required": ["toAndBack"] },
        { "required": ["toAsync"] },
        { "required": ["restartAt"] },
        { "required": ["subSequence"] }
      ],
      "additionalProperties": false
    },

    "subSequence": {
      "type": "object",
      "description": "Sub-sequences appear as colored boxes in sequences that can be zoomed into.",
      "required": ["name"],
      "properties": {
        "name": {
          "type": "string",
          "pattern": "^[^/~]*$",
          "description": "Name of the sub-sequence. Cannot contain / or ~"
        },
        "color": {
          "type": "string",
          "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$|^[a-zA-Z]+$",
          "description": "Box and text color. Any X11 color name or hex value. Defaults to perspective color."
        },
        "notes": {
          "type": "string",
          "description": "Notes that appear when zoomed into the sub-sequence. Supports markdown."
        },
        "steps": {
          "$ref": "#/$defs/stepArray",
          "description": "An array of steps"
        }
      },
      "additionalProperties": false
    },

    "aliasArray": {
      "type": "array",
      "description": "Aliases give convenient names to resource references.",
      "items": {
        "$ref": "#/$defs/alias"
      }
    },

    "alias": {
      "type": "object",
      "description": "Convenient names for resource references.",
      "required": ["alias", "for"],
      "properties": {
        "alias": {
          "type": "string",
          "pattern": "^[^/\\^*\\[\\],^]*$",
          "description": "Identifier for this alias. Can override existing resource id."
        },
        "for": {
          "type": "string",
          "description": "Value of this alias, typically comma-separated resource identifiers"
        }
      },
      "additionalProperties": false
    },

    "overrideArray": {
      "type": "array",
      "description": "Overrides are used to override parent and sizes of resources in a perspective.",
      "items": {
        "$ref": "#/$defs/override"
      }
    },

    "override": {
      "type": "object",
      "description": "Override resource properties in a perspective.",
      "required": ["resourceId"],
      "properties": {
        "resourceId": {
          "type": "string",
          "description": "Resource(s) to override in the perspective"
        },
        "parentId": {
          "type": "string",
          "description": "Different parent to assign, or none for no parent"
        },
        "scale": {
          "type": "number",
          "description": "Size adjustment for specified resource(s)"
        }
      },
      "additionalProperties": false
    },

    "slideArray": {
      "type": "array",
      "description": "Slides form the walkthrough for a perspective.",
      "items": {
        "$ref": "#/$defs/slide"
      }
    },

    "slide": {
      "type": "object",
      "description": "A slide in a perspective walkthrough.",
      "properties": {
        "text": {
          "type": "string",
          "description": "Text accompanying the slide. If not present, previous slide's text is used."
        },
        "select": {
          "type": "string",
          "description": "Resource(s) to select. Selected resources displayed prominently, others hidden."
        },
        "expand": {
          "type": "string",
          "description": "Resource or sub-sequence to expand (make full-screen). Use ^ for none."
        },
        "highlight": {
          "type": "string",
          "description": "Resource(s) to highlight with animated border."
        },
        "detail": {
          "type": "number",
          "minimum": 0.001,
          "maximum": 1,
          "default": 1,
          "description": "Level of detail used during the slide. Range: 0.001 (very low) to 1 (full detail)."
        }
      },
      "additionalProperties": false
    },

    "context": {
      "type": "object",
      "description": "Each context defines a view of the diagram resources.",
      "required": ["name"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Context name. Must be unique and cannot be Default."
        },
        "roots": {
          "$ref": "#/$defs/contextEntryArray",
          "description": "Context entries forming a tree structure"
        },
        "extends": {
          "type": "string",
          "description": "Previously-defined context(s) that this context extends."
        },
        "hidden": {
          "type": "boolean",
          "default": false,
          "description": "If true, context not shown in dropdown."
        }
      },
      "additionalProperties": false
    },

    "contextEntryArray": {
      "type": "array",
      "description": "Context entries form a tree-like structure for defining context.",
      "items": {
        "$ref": "#/$defs/contextEntry"
      }
    },

    "contextEntry": {
      "type": "object",
      "description": "Context entry defining resource visibility.",
      "required": ["resourceId"],
      "properties": {
        "resourceId": {
          "type": "string",
          "description": "Resource identifier(s) for this entry."
        },
        "children": {
          "$ref": "#/$defs/contextEntryArray",
          "description": "Child context entries. Cannot be defined if multiple resources specified in resourceId."
        }
      },
      "additionalProperties": false
    },

    "layout": {
      "type": "object",
      "description": "Layout parameters govern how child elements are laid out inside a parent.",
      "properties": {
        "compactness": {
          "type": "number",
          "minimum": 0.1,
          "maximum": 1,
          "default": 1,
          "description": "How compactly child resources are rendered. Affects only context resources with more than one child."
        },
        "sizes": {
          "type": "string",
          "enum": ["proportional", "uniform", "auto"],
          "default": "auto",
          "description": "How child resource sizes are determined."
        }
      },
      "additionalProperties": false
    },

    "perspectiveOptions": {
      "type": "object",
      "description": "Additional options for the perspective.",
      "properties": {},
      "additionalProperties": true
    },

    "import": {
      "type": "object",
      "description": "Imports define a list of diagrams to import and their namespaces.",
      "required": ["from", "namespace"],
      "properties": {
        "from": {
          "type": "string",
          "description": "The diagram to import"
        },
        "namespace": {
          "type": "string",
          "pattern": "^[^/\\^*\\[\\],^]*$",
          "description": "Namespace prefix for imported resources and perspectives. Cannot contain restricted characters."
        }
      },
      "additionalProperties": false
    }
  }
}