{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://local-flight-sim/schemas/flight-sim-api.schema.json",
  "title": "Local Flight Simulation API",
  "description": "Shared wire schema for the Web client and local simulation service. Heading convention: true heading 0 degrees points north, clockwise is positive, counter-clockwise is negative.",
  "$defs": {
    "Vec3": {
      "type": "array",
      "items": { "type": "number" },
      "minItems": 3,
      "maxItems": 3
    },
    "Quat": {
      "type": "array",
      "items": { "type": "number" },
      "minItems": 4,
      "maxItems": 4,
      "description": "[x, y, z, w]"
    },
    "InitialState": {
      "type": "object",
      "required": ["position", "velocityMps"],
      "properties": {
        "position": {
          "$ref": "#/$defs/Vec3",
          "description": "Local meters [east, up, north]."
        },
        "rotation": { "$ref": "#/$defs/Quat" },
        "velocityMps": { "type": "number", "exclusiveMinimum": 0 },
        "headingDeg": {
          "type": "number",
          "description": "True heading. 0 is north, clockwise positive, counter-clockwise negative."
        }
      },
      "additionalProperties": true
    },
    "FlightSample": {
      "type": "object",
      "required": ["t", "position", "rotation", "velocityMps", "headingDeg"],
      "properties": {
        "t": { "type": "number", "minimum": 0 },
        "position": {
          "$ref": "#/$defs/Vec3",
          "description": "Local meters [east, up, north]."
        },
        "rotation": { "$ref": "#/$defs/Quat" },
        "velocityMps": { "type": "number" },
        "headingDeg": {
          "type": "number",
          "description": "True heading. 0 is north, clockwise positive, counter-clockwise negative."
        },
        "angularVelocity": { "$ref": "#/$defs/Vec3" },
        "alphaDeg": { "type": "number" },
        "betaDeg": { "type": "number" },
        "loadFactor": { "type": "number" },
        "mach": { "type": "number" },
        "qbar": { "type": "number" },
        "verticalSpeedMps": { "type": "number" },
        "pitchRateDegS": { "type": "number" },
        "rollRateDegS": { "type": "number" },
        "yawRateDegS": { "type": "number" },
        "throttle": { "type": "number" },
        "controlInputs": {
          "type": "object",
          "properties": {
            "elevator": { "type": "number" },
            "aileron": { "type": "number" },
            "rudder": { "type": "number" },
            "throttle": { "type": "number" },
            "tvc": { "type": "number" },
            "speedbrake": { "type": "number" }
          },
          "additionalProperties": false
        },
        "controlSurfaces": {
          "type": "object",
          "properties": {
            "elevatorDeg": { "type": "number" },
            "aileronDeg": { "type": "number" },
            "rudderDeg": { "type": "number" },
            "tvcDeg": { "type": "number" },
            "speedbrakeNorm": { "type": "number" }
          },
          "additionalProperties": false
        },
        "fcs": {
          "type": "object",
          "properties": {
            "tvcPosNorm": { "type": "number" },
            "tvcInhibit": { "type": "number" },
            "thrustNorm": { "type": "number" },
            "throttleOverride": { "type": "number" },
            "pitchRateCmd": { "type": "number" }
          },
          "additionalProperties": true
        }
      },
      "additionalProperties": true
    },
    "SimulateRequest": {
      "type": "object",
      "required": ["aircraftId", "sampleRateHz", "durationSec", "initialState", "maneuver"],
      "properties": {
        "aircraftId": { "type": "string" },
        "sampleRateHz": { "type": "number", "exclusiveMinimum": 0 },
        "integrationRateHz": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Internal dynamics integration frequency. JSBSim defaults to 120 Hz; sampleRateHz remains the output sampling frequency."
        },
        "trim": {
          "type": "boolean",
          "description": "Whether the backend should attempt trim before simulation. F-22 maneuver research may use false when JSBSim trim cannot find a steady state."
        },
        "durationSec": { "type": "number", "exclusiveMinimum": 0 },
        "initialState": { "$ref": "#/$defs/InitialState" },
        "maneuver": {
          "type": "object",
          "required": ["type"],
          "properties": {
            "type": {
              "type": "string",
              "enum": ["straight", "climb", "descent", "level-turn", "control-script", "cobra"]
            },
            "parameters": {
              "type": "object",
              "description": "Maneuver-specific parameters. Cobra supports controlMode=open-loop|closed-loop. Closed-loop Cobra parameters include targetAlphaDeg, recoveryAlphaDeg, pitchRateLimitDegS, holdPitchRateDegS, pullDurationSec, holdDurationSec, recoveryDurationSec, maxElevatorCmd, recoveryElevatorCmd, pullTvcCmd, recoveryTvcCmd, throttleCmd, and speedbrakeCmd.",
              "additionalProperties": true
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    }
  }
}