{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://stellaops.io/schemas/policy-studio.v1.json",
  "title": "PolicyStudio",
  "description": "Policy Studio API contract for policy lifecycle management - drafts, compilation, simulation, and approval workflows",
  "type": "object",
  "$defs": {
    "PolicyDraft": {
      "type": "object",
      "description": "A policy draft in the editing workflow",
      "required": ["draftId", "tenantId", "name", "status", "createdAt"],
      "properties": {
        "draftId": {
          "type": "string",
          "format": "uuid"
        },
        "tenantId": {
          "type": "string"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256
        },
        "description": {
          "type": "string"
        },
        "status": {
          "$ref": "#/$defs/DraftStatus"
        },
        "dslSource": {
          "type": "string",
          "description": "StellaOps Policy DSL source code"
        },
        "compiledRego": {
          "type": "string",
          "description": "Compiled OPA Rego policy"
        },
        "compileDigest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$"
        },
        "validationErrors": {
          "type": "array",
          "items": {"$ref": "#/$defs/ValidationError"}
        },
        "createdAt": {
          "type": "string",
          "format": "date-time"
        },
        "createdBy": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time"
        },
        "submittedAt": {
          "type": "string",
          "format": "date-time"
        },
        "approvedAt": {
          "type": "string",
          "format": "date-time"
        },
        "approvedBy": {
          "type": "string"
        }
      }
    },
    "DraftStatus": {
      "type": "string",
      "description": "Policy draft lifecycle status",
      "enum": ["draft", "submitted", "approved", "active", "archived"]
    },
    "ValidationError": {
      "type": "object",
      "required": ["code", "message"],
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "line": {
          "type": "integer"
        },
        "column": {
          "type": "integer"
        },
        "severity": {
          "type": "string",
          "enum": ["error", "warning", "info"]
        }
      }
    },
    "CreateDraftRequest": {
      "type": "object",
      "required": ["name"],
      "properties": {
        "name": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "dslSource": {
          "type": "string"
        },
        "copyFrom": {
          "type": "string",
          "description": "Draft ID or policy ID to copy from"
        }
      }
    },
    "UpdateDraftRequest": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "dslSource": {
          "type": "string"
        }
      }
    },
    "CompileRequest": {
      "type": "object",
      "required": ["dslSource"],
      "properties": {
        "dslSource": {
          "type": "string",
          "description": "StellaOps Policy DSL to compile"
        },
        "validateOnly": {
          "type": "boolean",
          "default": false,
          "description": "Only validate, don't return compiled Rego"
        }
      }
    },
    "CompileResponse": {
      "type": "object",
      "required": ["success"],
      "properties": {
        "success": {
          "type": "boolean"
        },
        "compiledRego": {
          "type": "string"
        },
        "digest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$"
        },
        "errors": {
          "type": "array",
          "items": {"$ref": "#/$defs/ValidationError"}
        },
        "warnings": {
          "type": "array",
          "items": {"$ref": "#/$defs/ValidationError"}
        }
      }
    },
    "SimulationRequest": {
      "type": "object",
      "required": ["draftId", "inputs"],
      "properties": {
        "draftId": {
          "type": "string",
          "format": "uuid"
        },
        "inputs": {
          "type": "array",
          "items": {"$ref": "#/$defs/SimulationInput"},
          "minItems": 1
        },
        "compareWith": {
          "type": "string",
          "description": "Policy ID to compare results against"
        }
      }
    },
    "SimulationInput": {
      "type": "object",
      "required": ["componentPurl", "advisoryId"],
      "properties": {
        "componentPurl": {
          "type": "string"
        },
        "advisoryId": {
          "type": "string"
        },
        "cvss": {
          "type": "number"
        },
        "kev": {
          "type": "boolean"
        },
        "reachability": {
          "type": "number"
        },
        "vexStatus": {
          "type": "string",
          "enum": ["affected", "not_affected", "fixed", "under_investigation"]
        }
      }
    },
    "SimulationResponse": {
      "type": "object",
      "required": ["results"],
      "properties": {
        "results": {
          "type": "array",
          "items": {"$ref": "#/$defs/SimulationResult"}
        },
        "summary": {
          "$ref": "#/$defs/SimulationSummary"
        },
        "comparison": {
          "$ref": "#/$defs/SimulationComparison"
        }
      }
    },
    "SimulationResult": {
      "type": "object",
      "required": ["input", "decision", "severity"],
      "properties": {
        "input": {
          "$ref": "#/$defs/SimulationInput"
        },
        "decision": {
          "type": "string",
          "enum": ["allow", "review", "deny"]
        },
        "severity": {
          "type": "string",
          "enum": ["critical", "high", "medium", "low", "informational"]
        },
        "score": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "matchedRules": {
          "type": "array",
          "items": {"type": "string"}
        },
        "rationale": {
          "type": "string"
        }
      }
    },
    "SimulationSummary": {
      "type": "object",
      "properties": {
        "totalInputs": {
          "type": "integer"
        },
        "decisions": {
          "type": "object",
          "properties": {
            "allow": {"type": "integer"},
            "review": {"type": "integer"},
            "deny": {"type": "integer"}
          }
        },
        "severityCounts": {
          "type": "object",
          "additionalProperties": {"type": "integer"}
        }
      }
    },
    "SimulationComparison": {
      "type": "object",
      "properties": {
        "comparedWith": {
          "type": "string"
        },
        "decisionChanges": {
          "type": "integer"
        },
        "severityChanges": {
          "type": "integer"
        },
        "diff": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "input": {"$ref": "#/$defs/SimulationInput"},
              "oldDecision": {"type": "string"},
              "newDecision": {"type": "string"},
              "oldSeverity": {"type": "string"},
              "newSeverity": {"type": "string"}
            }
          }
        }
      }
    },
    "SubmitForReviewRequest": {
      "type": "object",
      "properties": {
        "comment": {
          "type": "string"
        },
        "reviewers": {
          "type": "array",
          "items": {"type": "string"}
        }
      }
    },
    "ApproveRequest": {
      "type": "object",
      "properties": {
        "comment": {
          "type": "string"
        }
      }
    },
    "ActivateRequest": {
      "type": "object",
      "properties": {
        "effectiveAt": {
          "type": "string",
          "format": "date-time",
          "description": "When activation should take effect"
        },
        "gradualRollout": {
          "type": "boolean",
          "default": false
        },
        "rolloutPercent": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100
        }
      }
    },
    "PolicyVersion": {
      "type": "object",
      "description": "An immutable policy version",
      "required": ["policyId", "version", "digest", "createdAt"],
      "properties": {
        "policyId": {
          "type": "string"
        },
        "version": {
          "type": "integer",
          "minimum": 1
        },
        "digest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$"
        },
        "dslSource": {
          "type": "string"
        },
        "compiledRego": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": ["active", "superseded", "archived"]
        },
        "createdAt": {
          "type": "string",
          "format": "date-time"
        },
        "createdBy": {
          "type": "string"
        },
        "activatedAt": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "EvaluationRequest": {
      "type": "object",
      "description": "Request to evaluate policy against input",
      "required": ["policyId", "input"],
      "properties": {
        "policyId": {
          "type": "string"
        },
        "version": {
          "type": "integer",
          "description": "Specific version, or omit for active"
        },
        "input": {
          "type": "object",
          "description": "Policy evaluation input"
        }
      }
    },
    "EvaluationResponse": {
      "type": "object",
      "required": ["policyId", "version", "digest", "decision"],
      "properties": {
        "policyId": {
          "type": "string"
        },
        "version": {
          "type": "integer"
        },
        "digest": {
          "type": "string"
        },
        "decision": {
          "type": "string",
          "enum": ["allow", "review", "deny"]
        },
        "correlationId": {
          "type": "string"
        },
        "cached": {
          "type": "boolean"
        },
        "evaluatedAt": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "AuthorityScopes": {
      "type": "object",
      "description": "Required authority scopes for Policy Studio",
      "properties": {
        "scopes": {
          "type": "array",
          "items": {"type": "string"},
          "default": [
            "policy:read",
            "policy:write",
            "policy:submit",
            "policy:approve",
            "policy:activate",
            "policy:archive"
          ]
        }
      }
    }
  },
  "examples": [
    {
      "draftId": "550e8400-e29b-41d4-a716-446655440000",
      "tenantId": "default",
      "name": "Critical Vuln Policy",
      "status": "draft",
      "dslSource": "rule kev_critical {\n  when kev = true\n  then severity = critical\n}",
      "createdAt": "2025-12-06T00:00:00Z",
      "createdBy": "user@example.com"
    }
  ]
}