{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://github.com/sengac/fspec/schemas/generic-foundation.schema.json",
  "title": "Generic Foundation Document Schema",
  "description": "A generic schema for foundation documents that works for ANY project type (web apps, CLI tools, libraries, services, mobile apps). Focuses ONLY on WHY (problem) and WHAT (solution), never HOW (implementation).",
  "type": "object",
  "required": ["version", "project", "problemSpace", "solutionSpace"],
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "type": "string",
      "description": "JSON Schema reference"
    },
    "version": {
      "type": "string",
      "description": "Schema version for migration compatibility",
      "pattern": "^\\d+\\.\\d+\\.\\d+$",
      "examples": ["2.0.0"]
    },
    "project": {
      "type": "object",
      "description": "REQUIRED: Project identity and basic metadata",
      "required": ["name", "vision", "projectType"],
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "description": "Project name",
          "minLength": 1
        },
        "vision": {
          "type": "string",
          "description": "One-sentence elevator pitch",
          "minLength": 1
        },
        "projectType": {
          "type": "string",
          "description": "Type of software project",
          "enum": [
            "web-app",
            "cli-tool",
            "library",
            "sdk",
            "mobile-app",
            "desktop-app",
            "service",
            "api",
            "other"
          ]
        },
        "repository": {
          "type": "string",
          "description": "Repository URL (optional)",
          "format": "uri"
        },
        "license": {
          "type": "string",
          "description": "License identifier (optional)",
          "examples": ["MIT", "Apache-2.0", "GPL-3.0"]
        }
      }
    },
    "problemSpace": {
      "type": "object",
      "description": "REQUIRED: Problem space (WHY) - captures the problems this project solves",
      "required": ["primaryProblem"],
      "additionalProperties": false,
      "properties": {
        "primaryProblem": {
          "$ref": "#/definitions/problem"
        },
        "additionalProblems": {
          "type": "array",
          "description": "Additional problems (can have thousands - use subFoundations for scalability)",
          "items": {
            "$ref": "#/definitions/problem"
          }
        },
        "currentStatePainPoints": {
          "type": "array",
          "description": "Current state pain points",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "solutionSpace": {
      "type": "object",
      "description": "REQUIRED: Solution space (WHAT) - broad capabilities only (3-7 high-level abilities)",
      "required": ["overview", "capabilities"],
      "additionalProperties": false,
      "properties": {
        "overview": {
          "type": "string",
          "description": "High-level solution overview",
          "minLength": 1
        },
        "capabilities": {
          "type": "array",
          "description": "High-level capabilities (3-7 recommended). Granular features belong in .feature files.",
          "minItems": 1,
          "items": {
            "$ref": "#/definitions/capability"
          }
        },
        "outOfScope": {
          "type": "array",
          "description": "What this solution does NOT do (optional)",
          "items": {
            "type": "string"
          }
        },
        "successCriteria": {
          "type": "array",
          "description": "Success criteria (optional)",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "subFoundations": {
      "type": "array",
      "description": "OPTIONAL: Hierarchical foundations - references to external sub-foundation documents",
      "items": {
        "type": "string",
        "description": "Path to sub-foundation file",
        "pattern": "\\.foundation\\.json$"
      }
    },
    "architectureDiagrams": {
      "type": "array",
      "description": "OPTIONAL: Architecture diagrams using Mermaid syntax",
      "items": {
        "$ref": "#/definitions/mermaidDiagram"
      }
    },
    "constraints": {
      "type": "object",
      "description": "OPTIONAL: Business, technical, and timeline constraints",
      "additionalProperties": false,
      "properties": {
        "business": {
          "type": "array",
          "items": { "type": "string" }
        },
        "technical": {
          "type": "array",
          "items": { "type": "string" }
        },
        "timeline": {
          "type": "array",
          "items": { "type": "string" }
        },
        "budget": {
          "type": "array",
          "items": { "type": "string" }
        }
      }
    },
    "personas": {
      "type": "array",
      "description": "OPTIONAL: Detailed personas (unlimited allowed, suggest 3-7 as best practice)",
      "items": {
        "$ref": "#/definitions/persona"
      }
    },
    "eventStorm": {
      "type": "object",
      "description": "OPTIONAL: Big Picture Event Storm for strategic domain understanding",
      "additionalProperties": false,
      "required": ["level", "items", "nextItemId"],
      "properties": {
        "level": {
          "type": "string",
          "const": "big_picture",
          "description": "Fixed value for foundation-level Event Storm"
        },
        "sessionDate": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp"
        },
        "facilitator": {
          "type": "string",
          "description": "Who facilitated the session"
        },
        "participants": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Who participated"
        },
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/eventStormItem"
          },
          "description": "All Event Storm artifacts"
        },
        "nextItemId": {
          "type": "integer",
          "minimum": 1,
          "description": "Auto-increment counter for stable IDs"
        }
      }
    }
  },
  "definitions": {
    "problem": {
      "type": "object",
      "description": "Problem definition with impact, frequency, and cost ratings",
      "required": ["title", "description", "impact"],
      "additionalProperties": false,
      "properties": {
        "title": {
          "type": "string",
          "minLength": 1
        },
        "description": {
          "type": "string",
          "minLength": 1
        },
        "impact": {
          "type": "string",
          "enum": ["high", "medium", "low"],
          "description": "Impact rating"
        },
        "frequency": {
          "type": "string",
          "enum": ["constant", "frequent", "occasional", "rare"],
          "description": "Frequency rating (optional)"
        },
        "cost": {
          "type": "string",
          "enum": ["critical", "significant", "moderate", "minor"],
          "description": "Cost rating (optional)"
        },
        "affectedStakeholders": {
          "type": "array",
          "description": "Stakeholders affected by this problem (optional)",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "capability": {
      "type": "object",
      "description": "High-level capability (WHAT the system does, not HOW)",
      "required": ["name", "description"],
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "description": "Capability name (e.g., 'User Authentication', NOT 'Login with OAuth')",
          "minLength": 1
        },
        "description": {
          "type": "string",
          "description": "Capability description (focus on WHAT, not HOW)",
          "minLength": 1
        },
        "rationale": {
          "type": "string",
          "description": "Why this capability is important (optional)"
        }
      }
    },
    "persona": {
      "type": "object",
      "description": "User persona (unlimited allowed, suggest 3-7)",
      "required": ["name", "description"],
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1
        },
        "description": {
          "type": "string",
          "minLength": 1
        },
        "goals": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "painPoints": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "mermaidDiagram": {
      "type": "object",
      "description": "Mermaid diagram (validated using mermaid.parse() with jsdom)",
      "required": ["title", "mermaidCode"],
      "additionalProperties": false,
      "properties": {
        "title": {
          "type": "string",
          "minLength": 1
        },
        "mermaidCode": {
          "type": "string",
          "description": "Mermaid diagram syntax",
          "minLength": 1
        },
        "description": {
          "type": "string",
          "description": "Diagram description (optional)"
        }
      }
    },
    "eventStormItem": {
      "description": "Discriminated union of all Event Storm item types",
      "oneOf": [
        { "$ref": "#/definitions/eventStormEvent" },
        { "$ref": "#/definitions/eventStormCommand" },
        { "$ref": "#/definitions/eventStormAggregate" },
        { "$ref": "#/definitions/eventStormPolicy" },
        { "$ref": "#/definitions/eventStormHotspot" },
        { "$ref": "#/definitions/eventStormExternalSystem" },
        { "$ref": "#/definitions/eventStormBoundedContext" }
      ]
    },
    "eventStormItemBase": {
      "type": "object",
      "description": "Base properties for all Event Storm items",
      "required": ["id", "type", "text", "deleted", "createdAt"],
      "properties": {
        "id": {
          "type": "integer",
          "minimum": 1,
          "description": "Auto-incrementing stable ID"
        },
        "type": {
          "type": "string",
          "description": "Item type discriminator"
        },
        "text": {
          "type": "string",
          "minLength": 1,
          "description": "The actual content"
        },
        "deleted": {
          "type": "boolean",
          "description": "Soft-delete flag"
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp"
        },
        "deletedAt": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp (only when deleted=true)"
        },
        "timestamp": {
          "type": "integer",
          "description": "For timeline visualization"
        },
        "boundedContext": {
          "type": "string",
          "description": "Optional bounded context association"
        },
        "relatedTo": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "IDs of related items for traceability"
        }
      }
    },
    "eventStormEvent": {
      "allOf": [
        { "$ref": "#/definitions/eventStormItemBase" },
        {
          "type": "object",
          "required": ["type", "color"],
          "properties": {
            "type": {
              "const": "event"
            },
            "color": {
              "const": "orange"
            }
          }
        }
      ]
    },
    "eventStormCommand": {
      "allOf": [
        { "$ref": "#/definitions/eventStormItemBase" },
        {
          "type": "object",
          "required": ["type", "color"],
          "properties": {
            "type": {
              "const": "command"
            },
            "color": {
              "const": "blue"
            },
            "actor": {
              "type": "string",
              "description": "Who executes the command"
            },
            "triggersEvent": {
              "type": "integer",
              "description": "ID of event this command triggers"
            }
          }
        }
      ]
    },
    "eventStormAggregate": {
      "allOf": [
        { "$ref": "#/definitions/eventStormItemBase" },
        {
          "type": "object",
          "required": ["type", "color"],
          "properties": {
            "type": {
              "const": "aggregate"
            },
            "color": {
              "const": "yellow"
            },
            "responsibilities": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "What this aggregate is responsible for"
            },
            "emits": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Domain event names this aggregate emits"
            }
          }
        }
      ]
    },
    "eventStormPolicy": {
      "allOf": [
        { "$ref": "#/definitions/eventStormItemBase" },
        {
          "type": "object",
          "required": ["type", "color"],
          "properties": {
            "type": {
              "const": "policy"
            },
            "color": {
              "const": "purple"
            },
            "when": {
              "type": "string",
              "description": "Trigger condition"
            },
            "then": {
              "type": "string",
              "description": "Resulting action"
            }
          }
        }
      ]
    },
    "eventStormHotspot": {
      "allOf": [
        { "$ref": "#/definitions/eventStormItemBase" },
        {
          "type": "object",
          "required": ["type", "color"],
          "properties": {
            "type": {
              "const": "hotspot"
            },
            "color": {
              "const": "red"
            },
            "concern": {
              "type": "string",
              "description": "Description of risk, uncertainty, or problem"
            }
          }
        }
      ]
    },
    "eventStormExternalSystem": {
      "allOf": [
        { "$ref": "#/definitions/eventStormItemBase" },
        {
          "type": "object",
          "required": ["type", "color"],
          "properties": {
            "type": {
              "const": "external_system"
            },
            "color": {
              "const": "pink"
            },
            "integrationType": {
              "type": "string",
              "description": "API, library, service, etc."
            }
          }
        }
      ]
    },
    "eventStormBoundedContext": {
      "allOf": [
        { "$ref": "#/definitions/eventStormItemBase" },
        {
          "type": "object",
          "required": ["type", "color"],
          "properties": {
            "type": {
              "const": "bounded_context"
            },
            "color": {
              "type": "null",
              "description": "Conceptual boundary, not a sticky note"
            },
            "description": {
              "type": "string",
              "description": "Scope and responsibilities"
            },
            "itemIds": {
              "type": "array",
              "items": {
                "type": "integer"
              },
              "description": "IDs of items within this bounded context"
            }
          }
        }
      ]
    }
  }
}