{
  "openapi": "3.0.0",
  "info": {
    "title": "dummyiot — IoT Mock API",
    "version": "1.0.0",
    "description": "A mock IoT API with realistic simulated data for prototyping without hardware. Current modules: Mashhad Wind Farm with 10 turbines and one industrial refrigerator, both on a fixed 5-second simulation grid."
  },
  "paths": {
    "/api/turbines/{id}/alerts": {
      "get": {
        "operationId": "get-api-turbines-{id}-alerts",
        "summary": "Get active alerts",
        "description": "Derives the currently active alerts for a turbine from its reported values and online state. Each alert contains an English code, severity, message, and the ISO timestamp at which the condition became true. Alerts are not stored as history.",
        "tags": [
          "Alerts"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Turbine identifier, for example WT-001."
            },
            "description": "Turbine identifier, for example WT-001.",
            "example": "WT-001"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AlertsResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/farm": {
      "get": {
        "operationId": "get-api-farm",
        "summary": "Farm information",
        "description": "Returns the single farm: its name, geographic centre, shared turbine model, turbine count, and 2x5 layout description.",
        "tags": [
          "Farm"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FarmResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/farm/layout": {
      "get": {
        "operationId": "get-api-farm-layout",
        "summary": "Farm layout",
        "description": "Returns all turbines with coordinates, grid row and column, row role, distance from the farm centre, derived online state, and active alerts. Intended for maps and schematics.",
        "tags": [
          "Farm"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FarmLayoutResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/farm/summary": {
      "get": {
        "operationId": "get-api-farm-summary",
        "summary": "Farm summary",
        "description": "Aggregates the current snapshot: online and offline counts, total active power, average wind speed, turbines with an error code, actionable warning/critical alerts, info-only conditions, affected turbines, and stale turbines.",
        "tags": [
          "Farm"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FarmSummaryResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/refrigerator": {
      "get": {
        "operationId": "get-api-refrigerator",
        "summary": "Get refrigerator",
        "description": "Returns the complete Digital Twin document for the single industrial refrigerator, including reported telemetry, desired operating limits, derived online state, and last_seen.",
        "tags": [
          "Refrigerator"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefrigeratorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/refrigerator/alerts": {
      "get": {
        "operationId": "get-api-refrigerator-alerts",
        "summary": "Get refrigerator alerts",
        "description": "Derives currently active alerts for the industrial refrigerator. Alerts are not stored as history.",
        "tags": [
          "Refrigerator"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefrigeratorAlertsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/refrigerator/desired": {
      "get": {
        "operationId": "get-api-refrigerator-desired",
        "summary": "Get refrigerator limits",
        "description": "Returns the configured temperature setpoint, maximum temperature, maximum humidity, and door alarm delay.",
        "tags": [
          "Refrigerator"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefrigeratorDesiredResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/refrigerator/recent": {
      "get": {
        "operationId": "get-api-refrigerator-recent",
        "summary": "Get refrigerator samples",
        "description": "Returns the last 20 samples received from the refrigerator. The device samples every 5 seconds, buffers six samples, and sends one batch every 30 seconds; this endpoint advances only when a batch arrives. Not a historical telemetry API.",
        "tags": [
          "Refrigerator"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefrigeratorRecentResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/refrigerator/reported": {
      "get": {
        "operationId": "get-api-refrigerator-reported",
        "summary": "Get refrigerator telemetry",
        "description": "Returns the newest sample from the latest received 30-second report batch: temperature, humidity, door, compressor, compressor-failure, power, and error fields.",
        "tags": [
          "Refrigerator"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefrigeratorReportedResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "get-api-health",
        "summary": "Service health",
        "description": "Returns process uptime, the number of online turbines, and the timing constants that drive the fixed-grid simulation. This endpoint also advances the in-memory simulation to the current time.",
        "tags": [
          "System"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/turbines": {
      "get": {
        "operationId": "get-api-turbines",
        "summary": "List turbines",
        "description": "Returns a paginated list of the ten turbine twins. Use online=true or online=false to filter by the derived online state. page must be at least 1 and size must be between 1 and 50.",
        "tags": [
          "Turbines"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "online",
            "required": false,
            "schema": {
              "type": "boolean",
              "description": "Filter by derived online state. Use \"true\" or \"false\"."
            },
            "description": "Filter by derived online state. Use \"true\" or \"false\".",
            "example": true
          },
          {
            "in": "query",
            "name": "page",
            "required": false,
            "schema": {
              "type": "number",
              "description": "1-based page number. Defaults to 1. Minimum 1."
            },
            "description": "1-based page number. Defaults to 1. Minimum 1.",
            "example": 1
          },
          {
            "in": "query",
            "name": "size",
            "required": false,
            "schema": {
              "type": "number",
              "description": "Page size between 1 and 50. Defaults to 20."
            },
            "description": "Page size between 1 and 50. Defaults to 20.",
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TurbineListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/turbines/{id}": {
      "get": {
        "operationId": "get-api-turbines-{id}",
        "summary": "Get one turbine",
        "description": "Returns the complete Digital Twin document for a single turbine, including the reported block, the desired settings, derived online state, and last_seen.",
        "tags": [
          "Turbines"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Turbine identifier, for example WT-001."
            },
            "description": "Turbine identifier, for example WT-001.",
            "example": "WT-001"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TurbineResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/turbines/{id}/desired": {
      "get": {
        "operationId": "get-api-turbines-{id}-desired",
        "summary": "Get desired settings",
        "description": "Returns only the desired settings block for a turbine: power limit and cut-in/cut-out wind speeds.",
        "tags": [
          "Turbines"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Turbine identifier, for example WT-001."
            },
            "description": "Turbine identifier, for example WT-001.",
            "example": "WT-001"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DesiredResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/turbines/{id}/recent": {
      "get": {
        "operationId": "get-api-turbines-{id}-recent",
        "summary": "Get recent samples",
        "description": "Returns up to RECENT_BUFFER_SIZE samples received from successful 30-second report batches. The turbine samples every 5 seconds locally, buffers six samples, and sends the batch every 30 seconds; requests between reports return identical data. This is a recent-samples convenience endpoint, not a historical telemetry API.",
        "tags": [
          "Turbines"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "type": "number",
              "description": "Number of most recent samples to return, between 1 and RECENT_BUFFER_SIZE."
            },
            "description": "Number of most recent samples to return, between 1 and RECENT_BUFFER_SIZE.",
            "example": 1
          },
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Turbine identifier, for example WT-001."
            },
            "description": "Turbine identifier, for example WT-001.",
            "example": "WT-001"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecentResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/turbines/{id}/reported": {
      "get": {
        "operationId": "get-api-turbines-{id}-reported",
        "summary": "Get reported telemetry",
        "description": "Returns only the reported block for a turbine: wind speed, power, rotor speed, gearbox temperature, nacelle direction, blade pitch, vibration, and error code.",
        "tags": [
          "Turbines"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Turbine identifier, for example WT-001."
            },
            "description": "Turbine identifier, for example WT-001.",
            "example": "WT-001"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportedResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Alerts"
    },
    {
      "name": "Farm"
    },
    {
      "name": "Refrigerator"
    },
    {
      "name": "System"
    },
    {
      "name": "Turbines"
    }
  ],
  "servers": [
    {
      "url": "",
      "description": "API server"
    }
  ],
  "components": {
    "schemas": {
      "AlertCode": {
        "type": "string",
        "enum": [
          "WIND_HIGH",
          "WIND_LOW",
          "GEARBOX_OVERHEAT",
          "VIBRATION_HIGH",
          "POWER_LIMITED",
          "OFFLINE",
          "ERROR_CODE"
        ]
      },
      "AlertListMeta": {
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2026-11-10T12:00:01.240Z",
            "description": "Server time at which the response was produced."
          },
          "turbine_id": {
            "type": "string",
            "example": "WT-001",
            "description": "Turbine identifier."
          },
          "count": {
            "type": "number",
            "example": 2,
            "description": "Number of active alerts."
          }
        },
        "required": [
          "turbine_id",
          "count"
        ]
      },
      "AlertSeverity": {
        "type": "string",
        "enum": [
          "info",
          "warning",
          "critical"
        ]
      },
      "AlertsResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "WIND_HIGH",
                    "WIND_LOW",
                    "GEARBOX_OVERHEAT",
                    "VIBRATION_HIGH",
                    "POWER_LIMITED",
                    "OFFLINE",
                    "ERROR_CODE"
                  ],
                  "example": "GEARBOX_OVERHEAT",
                  "description": "Stable machine-readable alert code."
                },
                "severity": {
                  "type": "string",
                  "enum": [
                    "info",
                    "warning",
                    "critical"
                  ],
                  "example": "critical",
                  "description": "Alert severity: info, warning, or critical."
                },
                "message": {
                  "type": "string",
                  "example": "Gearbox temperature is above 80 C.",
                  "description": "English diagnostic message."
                },
                "since": {
                  "type": "string",
                  "format": "date-time",
                  "example": "2026-11-10T12:00:00.000Z",
                  "description": "ISO 8601 timestamp of the transition into the active state."
                }
              },
              "required": [
                "code",
                "severity",
                "message",
                "since"
              ]
            },
            "description": "Currently active alerts."
          },
          "meta": {
            "type": "object",
            "properties": {
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "example": "2026-11-10T12:00:01.240Z",
                "description": "Server time at which the response was produced."
              },
              "turbine_id": {
                "type": "string",
                "example": "WT-001",
                "description": "Turbine identifier."
              },
              "count": {
                "type": "number",
                "example": 2,
                "description": "Number of active alerts."
              }
            },
            "required": [
              "turbine_id",
              "count"
            ],
            "description": "Alert metadata."
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "ApiMeta": {
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2026-11-10T12:00:01.240Z",
            "description": "Server time at which the response was produced."
          }
        },
        "required": [
          "timestamp"
        ]
      },
      "DesiredResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "power_limit_kw": {
                "type": "number",
                "example": 4200,
                "description": "Maximum allowed active power in kilowatts."
              },
              "cut_in_speed_ms": {
                "type": "number",
                "example": 3,
                "description": "Wind speed at which generation starts, in metres per second."
              },
              "cut_out_speed_ms": {
                "type": "number",
                "example": 25,
                "description": "Wind speed at which generation stops, in metres per second."
              }
            },
            "required": [
              "power_limit_kw",
              "cut_in_speed_ms",
              "cut_out_speed_ms"
            ],
            "description": "Read-only desired settings block."
          },
          "meta": {
            "type": "object",
            "properties": {
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "example": "2026-11-10T12:00:01.240Z",
                "description": "Server time at which the response was produced."
              }
            },
            "required": [
              "timestamp"
            ],
            "description": "Response metadata."
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "DesiredSettings": {
        "type": "object",
        "properties": {
          "power_limit_kw": {
            "type": "number",
            "example": 4200,
            "description": "Maximum allowed active power in kilowatts."
          },
          "cut_in_speed_ms": {
            "type": "number",
            "example": 3,
            "description": "Wind speed at which generation starts, in metres per second."
          },
          "cut_out_speed_ms": {
            "type": "number",
            "example": 25,
            "description": "Wind speed at which generation stops, in metres per second."
          }
        },
        "required": [
          "power_limit_kw",
          "cut_in_speed_ms",
          "cut_out_speed_ms"
        ]
      },
      "ErrorDetail": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "example": "TURBINE_NOT_FOUND",
            "description": "Stable machine-readable error code."
          },
          "message": {
            "type": "string",
            "example": "Turbine WT-099 was not found.",
            "description": "English error message."
          }
        },
        "required": [
          "code",
          "message"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "example": "TURBINE_NOT_FOUND",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "example": "Turbine WT-099 was not found.",
                "description": "English error message."
              }
            },
            "required": [
              "code",
              "message"
            ],
            "description": "Error payload."
          }
        },
        "required": [
          "error"
        ]
      },
      "FarmInfo": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "Mashhad Wind Farm",
            "description": "Farm name used by the API."
          },
          "center": {
            "type": "object",
            "properties": {
              "lat": {
                "type": "number",
                "example": 36.50135,
                "description": "Latitude in decimal degrees."
              },
              "lon": {
                "type": "number",
                "example": 59.1982,
                "description": "Longitude in decimal degrees."
              }
            },
            "required": [
              "lat",
              "lon"
            ],
            "description": "Geographic centre of the farm."
          },
          "turbine_count": {
            "type": "number",
            "example": 10,
            "description": "Number of turbines in the farm."
          },
          "model": {
            "type": "string",
            "example": "Vestas V150-4.2MW",
            "description": "Turbine model shared by the whole farm."
          },
          "layout": {
            "type": "object",
            "properties": {
              "rows": {
                "type": "number",
                "example": 2,
                "description": "Number of layout rows."
              },
              "columns": {
                "type": "number",
                "example": 5,
                "description": "Number of layout columns."
              },
              "spacing_m": {
                "type": "number",
                "example": 300,
                "description": "Distance between adjacent turbines in metres."
              },
              "orientation_deg": {
                "type": "number",
                "example": 245,
                "description": "Prevailing wind direction in degrees clockwise from north."
              },
              "arrangement": {
                "type": "string",
                "example": "2x5 grid",
                "description": "Human-readable layout description."
              }
            },
            "required": [
              "rows",
              "columns",
              "spacing_m",
              "orientation_deg",
              "arrangement"
            ],
            "description": "Spatial arrangement of the turbines."
          }
        },
        "required": [
          "name",
          "center",
          "turbine_count",
          "model",
          "layout"
        ]
      },
      "FarmLayoutInfo": {
        "type": "object",
        "properties": {
          "rows": {
            "type": "number",
            "example": 2,
            "description": "Number of layout rows."
          },
          "columns": {
            "type": "number",
            "example": 5,
            "description": "Number of layout columns."
          },
          "spacing_m": {
            "type": "number",
            "example": 300,
            "description": "Distance between adjacent turbines in metres."
          },
          "orientation_deg": {
            "type": "number",
            "example": 245,
            "description": "Prevailing wind direction in degrees clockwise from north."
          },
          "arrangement": {
            "type": "string",
            "example": "2x5 grid",
            "description": "Human-readable layout description."
          }
        },
        "required": [
          "rows",
          "columns",
          "spacing_m",
          "orientation_deg",
          "arrangement"
        ]
      },
      "FarmLayoutMeta": {
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2026-11-10T12:00:01.240Z",
            "description": "Server time at which the response was produced."
          },
          "layout": {
            "type": "object",
            "properties": {
              "rows": {
                "type": "number",
                "example": 2,
                "description": "Number of layout rows."
              },
              "columns": {
                "type": "number",
                "example": 5,
                "description": "Number of layout columns."
              },
              "spacing_m": {
                "type": "number",
                "example": 300,
                "description": "Distance between adjacent turbines in metres."
              },
              "orientation_deg": {
                "type": "number",
                "example": 245,
                "description": "Prevailing wind direction in degrees clockwise from north."
              },
              "arrangement": {
                "type": "string",
                "example": "2x5 grid",
                "description": "Human-readable layout description."
              }
            },
            "required": [
              "rows",
              "columns",
              "spacing_m",
              "orientation_deg",
              "arrangement"
            ],
            "description": "Farm layout description."
          },
          "center": {
            "type": "object",
            "properties": {
              "lat": {
                "type": "number",
                "example": 36.50135,
                "description": "Latitude in decimal degrees."
              },
              "lon": {
                "type": "number",
                "example": 59.1982,
                "description": "Longitude in decimal degrees."
              }
            },
            "required": [
              "lat",
              "lon"
            ],
            "description": "Farm centre."
          }
        },
        "required": [
          "layout",
          "center"
        ]
      },
      "FarmLayoutResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "example": "WT-001",
                  "description": "Turbine identifier."
                },
                "model": {
                  "type": "string",
                  "example": "Vestas V150-4.2MW",
                  "description": "Turbine model."
                },
                "location": {
                  "type": "object",
                  "properties": {
                    "lat": {
                      "type": "number",
                      "example": 36.50135,
                      "description": "Latitude in decimal degrees."
                    },
                    "lon": {
                      "type": "number",
                      "example": 59.1982,
                      "description": "Longitude in decimal degrees."
                    }
                  },
                  "required": [
                    "lat",
                    "lon"
                  ],
                  "description": "Generator position."
                },
                "row": {
                  "type": "number",
                  "example": 0,
                  "description": "Zero-based layout row."
                },
                "column": {
                  "type": "number",
                  "example": 0,
                  "description": "Zero-based layout column, ordered right to left."
                },
                "row_role": {
                  "type": "string",
                  "enum": [
                    "upstream",
                    "downstream"
                  ],
                  "example": "upstream",
                  "description": "Upstream row or downstream wake-affected row."
                },
                "online": {
                  "type": "boolean",
                  "description": "Derived online state at request time."
                },
                "distance_from_center_m": {
                  "type": "number",
                  "example": 632.5,
                  "description": "Distance from the farm centre in metres."
                },
                "alerts": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "WIND_HIGH",
                          "WIND_LOW",
                          "GEARBOX_OVERHEAT",
                          "VIBRATION_HIGH",
                          "POWER_LIMITED",
                          "OFFLINE",
                          "ERROR_CODE"
                        ],
                        "example": "GEARBOX_OVERHEAT",
                        "description": "Stable machine-readable alert code."
                      },
                      "severity": {
                        "type": "string",
                        "enum": [
                          "info",
                          "warning",
                          "critical"
                        ],
                        "example": "critical",
                        "description": "Alert severity: info, warning, or critical."
                      },
                      "message": {
                        "type": "string",
                        "example": "Gearbox temperature is above 80 C.",
                        "description": "English diagnostic message."
                      },
                      "since": {
                        "type": "string",
                        "format": "date-time",
                        "example": "2026-11-10T12:00:00.000Z",
                        "description": "ISO 8601 timestamp of the transition into the active state."
                      }
                    },
                    "required": [
                      "code",
                      "severity",
                      "message",
                      "since"
                    ]
                  },
                  "description": "Active alert conditions for this turbine."
                }
              },
              "required": [
                "id",
                "model",
                "location",
                "row",
                "column",
                "row_role",
                "online",
                "distance_from_center_m",
                "alerts"
              ]
            },
            "description": "Turbine positions."
          },
          "meta": {
            "type": "object",
            "properties": {
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "example": "2026-11-10T12:00:01.240Z",
                "description": "Server time at which the response was produced."
              },
              "layout": {
                "type": "object",
                "properties": {
                  "rows": {
                    "type": "number",
                    "example": 2,
                    "description": "Number of layout rows."
                  },
                  "columns": {
                    "type": "number",
                    "example": 5,
                    "description": "Number of layout columns."
                  },
                  "spacing_m": {
                    "type": "number",
                    "example": 300,
                    "description": "Distance between adjacent turbines in metres."
                  },
                  "orientation_deg": {
                    "type": "number",
                    "example": 245,
                    "description": "Prevailing wind direction in degrees clockwise from north."
                  },
                  "arrangement": {
                    "type": "string",
                    "example": "2x5 grid",
                    "description": "Human-readable layout description."
                  }
                },
                "required": [
                  "rows",
                  "columns",
                  "spacing_m",
                  "orientation_deg",
                  "arrangement"
                ],
                "description": "Farm layout description."
              },
              "center": {
                "type": "object",
                "properties": {
                  "lat": {
                    "type": "number",
                    "example": 36.50135,
                    "description": "Latitude in decimal degrees."
                  },
                  "lon": {
                    "type": "number",
                    "example": 59.1982,
                    "description": "Longitude in decimal degrees."
                  }
                },
                "required": [
                  "lat",
                  "lon"
                ],
                "description": "Farm centre."
              }
            },
            "required": [
              "layout",
              "center"
            ],
            "description": "Layout metadata."
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "FarmLayoutTurbine": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "WT-001",
            "description": "Turbine identifier."
          },
          "model": {
            "type": "string",
            "example": "Vestas V150-4.2MW",
            "description": "Turbine model."
          },
          "location": {
            "type": "object",
            "properties": {
              "lat": {
                "type": "number",
                "example": 36.50135,
                "description": "Latitude in decimal degrees."
              },
              "lon": {
                "type": "number",
                "example": 59.1982,
                "description": "Longitude in decimal degrees."
              }
            },
            "required": [
              "lat",
              "lon"
            ],
            "description": "Generator position."
          },
          "row": {
            "type": "number",
            "example": 0,
            "description": "Zero-based layout row."
          },
          "column": {
            "type": "number",
            "example": 0,
            "description": "Zero-based layout column, ordered right to left."
          },
          "row_role": {
            "type": "string",
            "enum": [
              "upstream",
              "downstream"
            ],
            "example": "upstream",
            "description": "Upstream row or downstream wake-affected row."
          },
          "online": {
            "type": "boolean",
            "description": "Derived online state at request time."
          },
          "distance_from_center_m": {
            "type": "number",
            "example": 632.5,
            "description": "Distance from the farm centre in metres."
          },
          "alerts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "WIND_HIGH",
                    "WIND_LOW",
                    "GEARBOX_OVERHEAT",
                    "VIBRATION_HIGH",
                    "POWER_LIMITED",
                    "OFFLINE",
                    "ERROR_CODE"
                  ],
                  "example": "GEARBOX_OVERHEAT",
                  "description": "Stable machine-readable alert code."
                },
                "severity": {
                  "type": "string",
                  "enum": [
                    "info",
                    "warning",
                    "critical"
                  ],
                  "example": "critical",
                  "description": "Alert severity: info, warning, or critical."
                },
                "message": {
                  "type": "string",
                  "example": "Gearbox temperature is above 80 C.",
                  "description": "English diagnostic message."
                },
                "since": {
                  "type": "string",
                  "format": "date-time",
                  "example": "2026-11-10T12:00:00.000Z",
                  "description": "ISO 8601 timestamp of the transition into the active state."
                }
              },
              "required": [
                "code",
                "severity",
                "message",
                "since"
              ]
            },
            "description": "Active alert conditions for this turbine."
          }
        },
        "required": [
          "id",
          "model",
          "location",
          "row",
          "column",
          "row_role",
          "online",
          "distance_from_center_m",
          "alerts"
        ]
      },
      "FarmResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "example": "Mashhad Wind Farm",
                "description": "Farm name used by the API."
              },
              "center": {
                "type": "object",
                "properties": {
                  "lat": {
                    "type": "number",
                    "example": 36.50135,
                    "description": "Latitude in decimal degrees."
                  },
                  "lon": {
                    "type": "number",
                    "example": 59.1982,
                    "description": "Longitude in decimal degrees."
                  }
                },
                "required": [
                  "lat",
                  "lon"
                ],
                "description": "Geographic centre of the farm."
              },
              "turbine_count": {
                "type": "number",
                "example": 10,
                "description": "Number of turbines in the farm."
              },
              "model": {
                "type": "string",
                "example": "Vestas V150-4.2MW",
                "description": "Turbine model shared by the whole farm."
              },
              "layout": {
                "type": "object",
                "properties": {
                  "rows": {
                    "type": "number",
                    "example": 2,
                    "description": "Number of layout rows."
                  },
                  "columns": {
                    "type": "number",
                    "example": 5,
                    "description": "Number of layout columns."
                  },
                  "spacing_m": {
                    "type": "number",
                    "example": 300,
                    "description": "Distance between adjacent turbines in metres."
                  },
                  "orientation_deg": {
                    "type": "number",
                    "example": 245,
                    "description": "Prevailing wind direction in degrees clockwise from north."
                  },
                  "arrangement": {
                    "type": "string",
                    "example": "2x5 grid",
                    "description": "Human-readable layout description."
                  }
                },
                "required": [
                  "rows",
                  "columns",
                  "spacing_m",
                  "orientation_deg",
                  "arrangement"
                ],
                "description": "Spatial arrangement of the turbines."
              }
            },
            "required": [
              "name",
              "center",
              "turbine_count",
              "model",
              "layout"
            ],
            "description": "Farm information."
          },
          "meta": {
            "type": "object",
            "properties": {
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "example": "2026-11-10T12:00:01.240Z",
                "description": "Server time at which the response was produced."
              }
            },
            "required": [
              "timestamp"
            ],
            "description": "Response metadata."
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "FarmSummary": {
        "type": "object",
        "properties": {
          "online_count": {
            "type": "number",
            "example": 10,
            "description": "Number of turbines whose last report is within the offline threshold."
          },
          "offline_count": {
            "type": "number",
            "example": 0,
            "description": "Number of turbines with a stale last report."
          },
          "error_count": {
            "type": "number",
            "example": 0,
            "description": "Number of turbines currently reporting an error code."
          },
          "total_power_kw": {
            "type": "number",
            "example": 31750.4,
            "description": "Total active power across the farm in kilowatts."
          },
          "avg_wind_speed_ms": {
            "type": "number",
            "example": 9.8,
            "description": "Mean wind speed across all turbines in metres per second."
          },
          "active_alerts_count": {
            "type": "number",
            "example": 2,
            "description": "Number of active warning or critical alerts across the farm."
          },
          "info_alerts_count": {
            "type": "number",
            "example": 10,
            "description": "Number of active info-only conditions across the farm."
          },
          "affected_turbines_count": {
            "type": "number",
            "example": 1,
            "description": "Number of turbines with at least one warning or critical alert."
          },
          "stale_turbines": {
            "type": "number",
            "example": 0,
            "description": "Number of turbines considered stale at request time."
          },
          "turbine_count": {
            "type": "number",
            "example": 10,
            "description": "Configured turbine count."
          },
          "total_power_limit_kw": {
            "type": "number",
            "example": 42000,
            "description": "Sum of configured power limits in kilowatts."
          }
        },
        "required": [
          "online_count",
          "offline_count",
          "error_count",
          "total_power_kw",
          "avg_wind_speed_ms",
          "active_alerts_count",
          "info_alerts_count",
          "affected_turbines_count",
          "stale_turbines",
          "turbine_count",
          "total_power_limit_kw"
        ]
      },
      "FarmSummaryResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "online_count": {
                "type": "number",
                "example": 10,
                "description": "Number of turbines whose last report is within the offline threshold."
              },
              "offline_count": {
                "type": "number",
                "example": 0,
                "description": "Number of turbines with a stale last report."
              },
              "error_count": {
                "type": "number",
                "example": 0,
                "description": "Number of turbines currently reporting an error code."
              },
              "total_power_kw": {
                "type": "number",
                "example": 31750.4,
                "description": "Total active power across the farm in kilowatts."
              },
              "avg_wind_speed_ms": {
                "type": "number",
                "example": 9.8,
                "description": "Mean wind speed across all turbines in metres per second."
              },
              "active_alerts_count": {
                "type": "number",
                "example": 2,
                "description": "Number of active warning or critical alerts across the farm."
              },
              "info_alerts_count": {
                "type": "number",
                "example": 10,
                "description": "Number of active info-only conditions across the farm."
              },
              "affected_turbines_count": {
                "type": "number",
                "example": 1,
                "description": "Number of turbines with at least one warning or critical alert."
              },
              "stale_turbines": {
                "type": "number",
                "example": 0,
                "description": "Number of turbines considered stale at request time."
              },
              "turbine_count": {
                "type": "number",
                "example": 10,
                "description": "Configured turbine count."
              },
              "total_power_limit_kw": {
                "type": "number",
                "example": 42000,
                "description": "Sum of configured power limits in kilowatts."
              }
            },
            "required": [
              "online_count",
              "offline_count",
              "error_count",
              "total_power_kw",
              "avg_wind_speed_ms",
              "active_alerts_count",
              "info_alerts_count",
              "affected_turbines_count",
              "stale_turbines",
              "turbine_count",
              "total_power_limit_kw"
            ],
            "description": "Aggregated farm state."
          },
          "meta": {
            "type": "object",
            "properties": {
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "example": "2026-11-10T12:00:01.240Z",
                "description": "Server time at which the response was produced."
              }
            },
            "required": [
              "timestamp"
            ],
            "description": "Response metadata."
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "GeoPoint": {
        "type": "object",
        "properties": {
          "lat": {
            "type": "number",
            "example": 36.50135,
            "description": "Latitude in decimal degrees."
          },
          "lon": {
            "type": "number",
            "example": 59.1982,
            "description": "Longitude in decimal degrees."
          }
        },
        "required": [
          "lat",
          "lon"
        ]
      },
      "HealthResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "example": "ok",
                "description": "Always \"ok\" while the process is serving requests."
              },
              "service": {
                "type": "string",
                "example": "mashhad-wind-farm-mock-api",
                "description": "Service name."
              },
              "uptime_seconds": {
                "type": "number",
                "example": 128.4,
                "description": "Seconds since the in-memory simulation started."
              },
              "started_at": {
                "type": "string",
                "format": "date-time",
                "description": "Simulation start time."
              },
              "turbine_count": {
                "type": "number",
                "example": 10,
                "description": "Configured turbine count."
              },
              "online_count": {
                "type": "number",
                "example": 10,
                "description": "Currently online turbines."
              },
              "sample_interval_ms": {
                "type": "number",
                "example": 5000,
                "description": "Fixed simulation sample interval in milliseconds."
              },
              "report_interval_sec": {
                "type": "number",
                "example": 30,
                "description": "Per-turbine report interval in seconds."
              },
              "offline_threshold_sec": {
                "type": "number",
                "example": 90,
                "description": "Offline threshold in seconds."
              },
              "recent_buffer_size": {
                "type": "number",
                "example": 20,
                "description": "Ring buffer capacity per turbine."
              }
            },
            "required": [
              "status",
              "service",
              "uptime_seconds",
              "started_at",
              "turbine_count",
              "online_count",
              "sample_interval_ms",
              "report_interval_sec",
              "offline_threshold_sec",
              "recent_buffer_size"
            ],
            "description": "Health status."
          },
          "meta": {
            "type": "object",
            "properties": {
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "example": "2026-11-10T12:00:01.240Z",
                "description": "Server time at which the response was produced."
              }
            },
            "required": [
              "timestamp"
            ],
            "description": "Response metadata."
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "HealthStatus": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "ok",
            "description": "Always \"ok\" while the process is serving requests."
          },
          "service": {
            "type": "string",
            "example": "mashhad-wind-farm-mock-api",
            "description": "Service name."
          },
          "uptime_seconds": {
            "type": "number",
            "example": 128.4,
            "description": "Seconds since the in-memory simulation started."
          },
          "started_at": {
            "type": "string",
            "format": "date-time",
            "description": "Simulation start time."
          },
          "turbine_count": {
            "type": "number",
            "example": 10,
            "description": "Configured turbine count."
          },
          "online_count": {
            "type": "number",
            "example": 10,
            "description": "Currently online turbines."
          },
          "sample_interval_ms": {
            "type": "number",
            "example": 5000,
            "description": "Fixed simulation sample interval in milliseconds."
          },
          "report_interval_sec": {
            "type": "number",
            "example": 30,
            "description": "Per-turbine report interval in seconds."
          },
          "offline_threshold_sec": {
            "type": "number",
            "example": 90,
            "description": "Offline threshold in seconds."
          },
          "recent_buffer_size": {
            "type": "number",
            "example": 20,
            "description": "Ring buffer capacity per turbine."
          }
        },
        "required": [
          "status",
          "service",
          "uptime_seconds",
          "started_at",
          "turbine_count",
          "online_count",
          "sample_interval_ms",
          "report_interval_sec",
          "offline_threshold_sec",
          "recent_buffer_size"
        ]
      },
      "PageMeta": {
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2026-11-10T12:00:01.240Z",
            "description": "Server time at which the response was produced."
          },
          "page": {
            "type": "number",
            "example": 1,
            "description": "Current 1-based page."
          },
          "size": {
            "type": "number",
            "example": 20,
            "description": "Page size."
          },
          "total": {
            "type": "number",
            "example": 10,
            "description": "Total matching turbines."
          },
          "total_pages": {
            "type": "number",
            "example": 1,
            "description": "Total number of pages."
          }
        },
        "required": [
          "page",
          "size",
          "total",
          "total_pages"
        ]
      },
      "RecentQuery": {
        "type": "object",
        "properties": {
          "limit": {
            "type": "number",
            "description": "Number of most recent samples to return, between 1 and RECENT_BUFFER_SIZE."
          }
        }
      },
      "RecentResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "wind_speed_ms": {
                  "type": "number",
                  "example": 8.4,
                  "description": "Current measured wind speed in metres per second."
                },
                "power_output_kw": {
                  "type": "number",
                  "example": 3100,
                  "description": "Current active power in kilowatts."
                },
                "rotor_rpm": {
                  "type": "number",
                  "example": 12.1,
                  "description": "Rotor speed in revolutions per minute."
                },
                "gearbox_temp_c": {
                  "type": "number",
                  "example": 62.3,
                  "description": "Gearbox oil temperature in degrees Celsius."
                },
                "nacelle_direction_deg": {
                  "type": "number",
                  "example": 245,
                  "description": "Nacelle heading in degrees clockwise from north."
                },
                "blade_pitch_deg": {
                  "type": "number",
                  "example": 4.2,
                  "description": "Collective blade pitch angle in degrees."
                },
                "vibration_mm_s": {
                  "type": "number",
                  "example": 1.8,
                  "description": "Nacelle vibration velocity in millimetres per second."
                },
                "error_code": {
                  "type": "string",
                  "nullable": true,
                  "example": null,
                  "description": "Active device error code, or null when the turbine reports no fault."
                },
                "timestamp": {
                  "type": "string",
                  "format": "date-time",
                  "example": "2026-11-10T11:58:25.000Z",
                  "description": "Device sample timestamp on the fixed 5-second grid."
                }
              },
              "required": [
                "timestamp"
              ]
            },
            "description": "Last received samples, oldest first. New samples arrive in six-sample report batches. Not a historical telemetry API."
          },
          "meta": {
            "type": "object",
            "properties": {
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "example": "2026-11-10T12:00:01.240Z",
                "description": "Server time at which the response was produced."
              },
              "interval_ms": {
                "type": "number",
                "example": 5000,
                "description": "Fixed device sampling interval in milliseconds."
              },
              "batch_size": {
                "type": "number",
                "example": 6,
                "description": "Number of samples delivered in each report."
              },
              "report_interval_ms": {
                "type": "number",
                "example": 30000,
                "description": "Device report interval in milliseconds."
              },
              "count": {
                "type": "number",
                "example": 20,
                "description": "Number of samples in the response."
              },
              "window_seconds": {
                "type": "number",
                "example": 95,
                "description": "Approximate coverage of the returned samples in seconds."
              }
            },
            "required": [
              "interval_ms",
              "batch_size",
              "report_interval_ms",
              "count",
              "window_seconds"
            ],
            "description": "Sampling and report-batch metadata."
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "RecentSample": {
        "type": "object",
        "properties": {
          "wind_speed_ms": {
            "type": "number",
            "example": 8.4,
            "description": "Current measured wind speed in metres per second."
          },
          "power_output_kw": {
            "type": "number",
            "example": 3100,
            "description": "Current active power in kilowatts."
          },
          "rotor_rpm": {
            "type": "number",
            "example": 12.1,
            "description": "Rotor speed in revolutions per minute."
          },
          "gearbox_temp_c": {
            "type": "number",
            "example": 62.3,
            "description": "Gearbox oil temperature in degrees Celsius."
          },
          "nacelle_direction_deg": {
            "type": "number",
            "example": 245,
            "description": "Nacelle heading in degrees clockwise from north."
          },
          "blade_pitch_deg": {
            "type": "number",
            "example": 4.2,
            "description": "Collective blade pitch angle in degrees."
          },
          "vibration_mm_s": {
            "type": "number",
            "example": 1.8,
            "description": "Nacelle vibration velocity in millimetres per second."
          },
          "error_code": {
            "type": "string",
            "nullable": true,
            "example": null,
            "description": "Active device error code, or null when the turbine reports no fault."
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2026-11-10T11:58:25.000Z",
            "description": "Device sample timestamp on the fixed 5-second grid."
          }
        },
        "required": [
          "timestamp"
        ]
      },
      "RecentSamplesMeta": {
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2026-11-10T12:00:01.240Z",
            "description": "Server time at which the response was produced."
          },
          "interval_ms": {
            "type": "number",
            "example": 5000,
            "description": "Fixed device sampling interval in milliseconds."
          },
          "batch_size": {
            "type": "number",
            "example": 6,
            "description": "Number of samples delivered in each report."
          },
          "report_interval_ms": {
            "type": "number",
            "example": 30000,
            "description": "Device report interval in milliseconds."
          },
          "count": {
            "type": "number",
            "example": 20,
            "description": "Number of samples in the response."
          },
          "window_seconds": {
            "type": "number",
            "example": 95,
            "description": "Approximate coverage of the returned samples in seconds."
          }
        },
        "required": [
          "interval_ms",
          "batch_size",
          "report_interval_ms",
          "count",
          "window_seconds"
        ]
      },
      "RefrigeratorAlert": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "TEMPERATURE_HIGH",
              "DOOR_OPEN",
              "COMPRESSOR_FAULT",
              "HUMIDITY_HIGH",
              "OFFLINE",
              "ERROR_CODE"
            ],
            "example": "DOOR_OPEN",
            "description": "Stable machine-readable alert code."
          },
          "severity": {
            "type": "string",
            "enum": [
              "info",
              "warning",
              "critical"
            ],
            "example": "warning",
            "description": "Alert severity: info, warning, or critical."
          },
          "message": {
            "type": "string",
            "example": "The refrigerator door has been open longer than the configured delay.",
            "description": "English diagnostic message."
          },
          "since": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp of the transition into the active state."
          }
        },
        "required": [
          "code",
          "severity",
          "message",
          "since"
        ]
      },
      "RefrigeratorAlertCode": {
        "type": "string",
        "enum": [
          "TEMPERATURE_HIGH",
          "DOOR_OPEN",
          "COMPRESSOR_FAULT",
          "HUMIDITY_HIGH",
          "OFFLINE",
          "ERROR_CODE"
        ]
      },
      "RefrigeratorAlertListMeta": {
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2026-11-10T12:00:01.240Z",
            "description": "Server time at which the response was produced."
          },
          "device_id": {
            "type": "string",
            "example": "FR-001",
            "description": "Device identifier."
          },
          "count": {
            "type": "number",
            "example": 1,
            "description": "Number of active alerts."
          }
        },
        "required": [
          "device_id",
          "count"
        ]
      },
      "RefrigeratorAlertsResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "TEMPERATURE_HIGH",
                    "DOOR_OPEN",
                    "COMPRESSOR_FAULT",
                    "HUMIDITY_HIGH",
                    "OFFLINE",
                    "ERROR_CODE"
                  ],
                  "example": "DOOR_OPEN",
                  "description": "Stable machine-readable alert code."
                },
                "severity": {
                  "type": "string",
                  "enum": [
                    "info",
                    "warning",
                    "critical"
                  ],
                  "example": "warning",
                  "description": "Alert severity: info, warning, or critical."
                },
                "message": {
                  "type": "string",
                  "example": "The refrigerator door has been open longer than the configured delay.",
                  "description": "English diagnostic message."
                },
                "since": {
                  "type": "string",
                  "format": "date-time",
                  "description": "ISO 8601 timestamp of the transition into the active state."
                }
              },
              "required": [
                "code",
                "severity",
                "message",
                "since"
              ]
            },
            "description": "Currently active refrigerator alerts."
          },
          "meta": {
            "type": "object",
            "properties": {
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "example": "2026-11-10T12:00:01.240Z",
                "description": "Server time at which the response was produced."
              },
              "device_id": {
                "type": "string",
                "example": "FR-001",
                "description": "Device identifier."
              },
              "count": {
                "type": "number",
                "example": 1,
                "description": "Number of active alerts."
              }
            },
            "required": [
              "device_id",
              "count"
            ],
            "description": "Alert metadata."
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "RefrigeratorDesiredResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "setpoint_c": {
                "type": "number",
                "example": 4,
                "description": "Target cooling temperature in degrees Celsius."
              },
              "max_temperature_c": {
                "type": "number",
                "example": 8,
                "description": "Highest allowed operating temperature in degrees Celsius."
              },
              "max_humidity_pct": {
                "type": "number",
                "example": 75,
                "description": "Highest allowed relative humidity percentage."
              },
              "door_alarm_delay_sec": {
                "type": "number",
                "example": 180,
                "description": "Seconds the door may stay open before a warning is raised."
              }
            },
            "required": [
              "setpoint_c",
              "max_temperature_c",
              "max_humidity_pct",
              "door_alarm_delay_sec"
            ],
            "description": "Operating envelope and alarm thresholds."
          },
          "meta": {
            "type": "object",
            "properties": {
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "example": "2026-11-10T12:00:01.240Z",
                "description": "Server time at which the response was produced."
              }
            },
            "required": [
              "timestamp"
            ],
            "description": "Response metadata."
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "RefrigeratorDesiredSettings": {
        "type": "object",
        "properties": {
          "setpoint_c": {
            "type": "number",
            "example": 4,
            "description": "Target cooling temperature in degrees Celsius."
          },
          "max_temperature_c": {
            "type": "number",
            "example": 8,
            "description": "Highest allowed operating temperature in degrees Celsius."
          },
          "max_humidity_pct": {
            "type": "number",
            "example": 75,
            "description": "Highest allowed relative humidity percentage."
          },
          "door_alarm_delay_sec": {
            "type": "number",
            "example": 180,
            "description": "Seconds the door may stay open before a warning is raised."
          }
        },
        "required": [
          "setpoint_c",
          "max_temperature_c",
          "max_humidity_pct",
          "door_alarm_delay_sec"
        ]
      },
      "RefrigeratorRecentMeta": {
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2026-11-10T12:00:01.240Z",
            "description": "Server time at which the response was produced."
          },
          "interval_ms": {
            "type": "number",
            "example": 5000,
            "description": "Fixed device sampling interval in milliseconds."
          },
          "batch_size": {
            "type": "number",
            "example": 6,
            "description": "Number of samples delivered in each report."
          },
          "report_interval_ms": {
            "type": "number",
            "example": 30000,
            "description": "Device report interval in milliseconds."
          },
          "count": {
            "type": "number",
            "example": 20,
            "description": "Number of samples in the response."
          },
          "window_seconds": {
            "type": "number",
            "example": 95,
            "description": "Approximate coverage of the returned samples in seconds."
          }
        },
        "required": [
          "interval_ms",
          "batch_size",
          "report_interval_ms",
          "count",
          "window_seconds"
        ]
      },
      "RefrigeratorRecentResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "temperature_c": {
                  "type": "number",
                  "example": 3.8,
                  "description": "Internal air temperature in degrees Celsius."
                },
                "humidity_pct": {
                  "type": "number",
                  "example": 58.4,
                  "description": "Relative humidity percentage."
                },
                "door_open": {
                  "type": "boolean",
                  "example": false,
                  "description": "Whether the door is currently open."
                },
                "compressor_on": {
                  "type": "boolean",
                  "example": true,
                  "description": "Whether the compressor is running."
                },
                "compressor_fault": {
                  "type": "boolean",
                  "example": false,
                  "description": "Whether the compressor is in a temporary failure state."
                },
                "power_draw_kw": {
                  "type": "number",
                  "example": 1.47,
                  "description": "Current electrical draw in kilowatts."
                },
                "error_code": {
                  "type": "string",
                  "nullable": true,
                  "example": null,
                  "description": "Active device error code, or null when there is no fault."
                },
                "timestamp": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Device sample timestamp on the fixed 5-second grid."
                }
              },
              "required": [
                "timestamp"
              ]
            },
            "description": "Last 20 received samples, oldest first. New samples arrive in six-sample batches. Not a historical telemetry API."
          },
          "meta": {
            "type": "object",
            "properties": {
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "example": "2026-11-10T12:00:01.240Z",
                "description": "Server time at which the response was produced."
              },
              "interval_ms": {
                "type": "number",
                "example": 5000,
                "description": "Fixed device sampling interval in milliseconds."
              },
              "batch_size": {
                "type": "number",
                "example": 6,
                "description": "Number of samples delivered in each report."
              },
              "report_interval_ms": {
                "type": "number",
                "example": 30000,
                "description": "Device report interval in milliseconds."
              },
              "count": {
                "type": "number",
                "example": 20,
                "description": "Number of samples in the response."
              },
              "window_seconds": {
                "type": "number",
                "example": 95,
                "description": "Approximate coverage of the returned samples in seconds."
              }
            },
            "required": [
              "interval_ms",
              "batch_size",
              "report_interval_ms",
              "count",
              "window_seconds"
            ],
            "description": "Sampling and report-batch metadata."
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "RefrigeratorRecentSample": {
        "type": "object",
        "properties": {
          "temperature_c": {
            "type": "number",
            "example": 3.8,
            "description": "Internal air temperature in degrees Celsius."
          },
          "humidity_pct": {
            "type": "number",
            "example": 58.4,
            "description": "Relative humidity percentage."
          },
          "door_open": {
            "type": "boolean",
            "example": false,
            "description": "Whether the door is currently open."
          },
          "compressor_on": {
            "type": "boolean",
            "example": true,
            "description": "Whether the compressor is running."
          },
          "compressor_fault": {
            "type": "boolean",
            "example": false,
            "description": "Whether the compressor is in a temporary failure state."
          },
          "power_draw_kw": {
            "type": "number",
            "example": 1.47,
            "description": "Current electrical draw in kilowatts."
          },
          "error_code": {
            "type": "string",
            "nullable": true,
            "example": null,
            "description": "Active device error code, or null when there is no fault."
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Device sample timestamp on the fixed 5-second grid."
          }
        },
        "required": [
          "timestamp"
        ]
      },
      "RefrigeratorReportedResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "temperature_c": {
                "type": "number",
                "example": 3.8,
                "description": "Internal air temperature in degrees Celsius."
              },
              "humidity_pct": {
                "type": "number",
                "example": 58.4,
                "description": "Relative humidity percentage."
              },
              "door_open": {
                "type": "boolean",
                "example": false,
                "description": "Whether the door is currently open."
              },
              "compressor_on": {
                "type": "boolean",
                "example": true,
                "description": "Whether the compressor is running."
              },
              "compressor_fault": {
                "type": "boolean",
                "example": false,
                "description": "Whether the compressor is in a temporary failure state."
              },
              "power_draw_kw": {
                "type": "number",
                "example": 1.47,
                "description": "Current electrical draw in kilowatts."
              },
              "error_code": {
                "type": "string",
                "nullable": true,
                "example": null,
                "description": "Active device error code, or null when there is no fault."
              }
            },
            "required": [
              "temperature_c",
              "humidity_pct",
              "door_open",
              "compressor_on",
              "compressor_fault",
              "power_draw_kw",
              "error_code"
            ],
            "description": "Newest sample from the latest received report batch."
          },
          "meta": {
            "type": "object",
            "properties": {
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "example": "2026-11-10T12:00:01.240Z",
                "description": "Server time at which the response was produced."
              }
            },
            "required": [
              "timestamp"
            ],
            "description": "Response metadata."
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "RefrigeratorReportedTelemetry": {
        "type": "object",
        "properties": {
          "temperature_c": {
            "type": "number",
            "example": 3.8,
            "description": "Internal air temperature in degrees Celsius."
          },
          "humidity_pct": {
            "type": "number",
            "example": 58.4,
            "description": "Relative humidity percentage."
          },
          "door_open": {
            "type": "boolean",
            "example": false,
            "description": "Whether the door is currently open."
          },
          "compressor_on": {
            "type": "boolean",
            "example": true,
            "description": "Whether the compressor is running."
          },
          "compressor_fault": {
            "type": "boolean",
            "example": false,
            "description": "Whether the compressor is in a temporary failure state."
          },
          "power_draw_kw": {
            "type": "number",
            "example": 1.47,
            "description": "Current electrical draw in kilowatts."
          },
          "error_code": {
            "type": "string",
            "nullable": true,
            "example": null,
            "description": "Active device error code, or null when there is no fault."
          }
        },
        "required": [
          "temperature_c",
          "humidity_pct",
          "door_open",
          "compressor_on",
          "compressor_fault",
          "power_draw_kw",
          "error_code"
        ]
      },
      "RefrigeratorResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "example": "FR-001",
                "description": "Device identifier."
              },
              "name": {
                "type": "string",
                "example": "Industrial Refrigerator",
                "description": "Human-readable device name."
              },
              "model": {
                "type": "string",
                "example": "ArcticPro IR-1200",
                "description": "Device model."
              },
              "site": {
                "type": "string",
                "example": "Mashhad Cold Storage",
                "description": "Site where the unit is installed."
              },
              "location": {
                "type": "object",
                "properties": {
                  "lat": {
                    "type": "number",
                    "example": 36.50135,
                    "description": "Latitude in decimal degrees."
                  },
                  "lon": {
                    "type": "number",
                    "example": 59.1982,
                    "description": "Longitude in decimal degrees."
                  }
                },
                "required": [
                  "lat",
                  "lon"
                ],
                "description": "Device position."
              },
              "online": {
                "type": "boolean",
                "description": "Derived from the age of last_seen."
              },
              "firmware": {
                "type": "string",
                "example": "1.4.2",
                "description": "Controller firmware version."
              },
              "reported": {
                "type": "object",
                "properties": {
                  "temperature_c": {
                    "type": "number",
                    "example": 3.8,
                    "description": "Internal air temperature in degrees Celsius."
                  },
                  "humidity_pct": {
                    "type": "number",
                    "example": 58.4,
                    "description": "Relative humidity percentage."
                  },
                  "door_open": {
                    "type": "boolean",
                    "example": false,
                    "description": "Whether the door is currently open."
                  },
                  "compressor_on": {
                    "type": "boolean",
                    "example": true,
                    "description": "Whether the compressor is running."
                  },
                  "compressor_fault": {
                    "type": "boolean",
                    "example": false,
                    "description": "Whether the compressor is in a temporary failure state."
                  },
                  "power_draw_kw": {
                    "type": "number",
                    "example": 1.47,
                    "description": "Current electrical draw in kilowatts."
                  },
                  "error_code": {
                    "type": "string",
                    "nullable": true,
                    "example": null,
                    "description": "Active device error code, or null when there is no fault."
                  }
                },
                "required": [
                  "temperature_c",
                  "humidity_pct",
                  "door_open",
                  "compressor_on",
                  "compressor_fault",
                  "power_draw_kw",
                  "error_code"
                ],
                "description": "Newest sample from the latest received report batch."
              },
              "desired": {
                "type": "object",
                "properties": {
                  "setpoint_c": {
                    "type": "number",
                    "example": 4,
                    "description": "Target cooling temperature in degrees Celsius."
                  },
                  "max_temperature_c": {
                    "type": "number",
                    "example": 8,
                    "description": "Highest allowed operating temperature in degrees Celsius."
                  },
                  "max_humidity_pct": {
                    "type": "number",
                    "example": 75,
                    "description": "Highest allowed relative humidity percentage."
                  },
                  "door_alarm_delay_sec": {
                    "type": "number",
                    "example": 180,
                    "description": "Seconds the door may stay open before a warning is raised."
                  }
                },
                "required": [
                  "setpoint_c",
                  "max_temperature_c",
                  "max_humidity_pct",
                  "door_alarm_delay_sec"
                ],
                "description": "Operating envelope and alarm thresholds."
              },
              "last_seen": {
                "type": "string",
                "format": "date-time",
                "description": "Time of the most recent received report batch."
              }
            },
            "required": [
              "id",
              "name",
              "model",
              "site",
              "location",
              "online",
              "firmware",
              "reported",
              "desired",
              "last_seen"
            ],
            "description": "Refrigerator Digital Twin document."
          },
          "meta": {
            "type": "object",
            "properties": {
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "example": "2026-11-10T12:00:01.240Z",
                "description": "Server time at which the response was produced."
              }
            },
            "required": [
              "timestamp"
            ],
            "description": "Response metadata."
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "RefrigeratorTwin": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "FR-001",
            "description": "Device identifier."
          },
          "name": {
            "type": "string",
            "example": "Industrial Refrigerator",
            "description": "Human-readable device name."
          },
          "model": {
            "type": "string",
            "example": "ArcticPro IR-1200",
            "description": "Device model."
          },
          "site": {
            "type": "string",
            "example": "Mashhad Cold Storage",
            "description": "Site where the unit is installed."
          },
          "location": {
            "type": "object",
            "properties": {
              "lat": {
                "type": "number",
                "example": 36.50135,
                "description": "Latitude in decimal degrees."
              },
              "lon": {
                "type": "number",
                "example": 59.1982,
                "description": "Longitude in decimal degrees."
              }
            },
            "required": [
              "lat",
              "lon"
            ],
            "description": "Device position."
          },
          "online": {
            "type": "boolean",
            "description": "Derived from the age of last_seen."
          },
          "firmware": {
            "type": "string",
            "example": "1.4.2",
            "description": "Controller firmware version."
          },
          "reported": {
            "type": "object",
            "properties": {
              "temperature_c": {
                "type": "number",
                "example": 3.8,
                "description": "Internal air temperature in degrees Celsius."
              },
              "humidity_pct": {
                "type": "number",
                "example": 58.4,
                "description": "Relative humidity percentage."
              },
              "door_open": {
                "type": "boolean",
                "example": false,
                "description": "Whether the door is currently open."
              },
              "compressor_on": {
                "type": "boolean",
                "example": true,
                "description": "Whether the compressor is running."
              },
              "compressor_fault": {
                "type": "boolean",
                "example": false,
                "description": "Whether the compressor is in a temporary failure state."
              },
              "power_draw_kw": {
                "type": "number",
                "example": 1.47,
                "description": "Current electrical draw in kilowatts."
              },
              "error_code": {
                "type": "string",
                "nullable": true,
                "example": null,
                "description": "Active device error code, or null when there is no fault."
              }
            },
            "required": [
              "temperature_c",
              "humidity_pct",
              "door_open",
              "compressor_on",
              "compressor_fault",
              "power_draw_kw",
              "error_code"
            ],
            "description": "Newest sample from the latest received report batch."
          },
          "desired": {
            "type": "object",
            "properties": {
              "setpoint_c": {
                "type": "number",
                "example": 4,
                "description": "Target cooling temperature in degrees Celsius."
              },
              "max_temperature_c": {
                "type": "number",
                "example": 8,
                "description": "Highest allowed operating temperature in degrees Celsius."
              },
              "max_humidity_pct": {
                "type": "number",
                "example": 75,
                "description": "Highest allowed relative humidity percentage."
              },
              "door_alarm_delay_sec": {
                "type": "number",
                "example": 180,
                "description": "Seconds the door may stay open before a warning is raised."
              }
            },
            "required": [
              "setpoint_c",
              "max_temperature_c",
              "max_humidity_pct",
              "door_alarm_delay_sec"
            ],
            "description": "Operating envelope and alarm thresholds."
          },
          "last_seen": {
            "type": "string",
            "format": "date-time",
            "description": "Time of the most recent received report batch."
          }
        },
        "required": [
          "id",
          "name",
          "model",
          "site",
          "location",
          "online",
          "firmware",
          "reported",
          "desired",
          "last_seen"
        ]
      },
      "ReportedResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "wind_speed_ms": {
                "type": "number",
                "example": 8.4,
                "description": "Current measured wind speed in metres per second."
              },
              "power_output_kw": {
                "type": "number",
                "example": 3100,
                "description": "Current active power in kilowatts."
              },
              "rotor_rpm": {
                "type": "number",
                "example": 12.1,
                "description": "Rotor speed in revolutions per minute."
              },
              "gearbox_temp_c": {
                "type": "number",
                "example": 62.3,
                "description": "Gearbox oil temperature in degrees Celsius."
              },
              "nacelle_direction_deg": {
                "type": "number",
                "example": 245,
                "description": "Nacelle heading in degrees clockwise from north."
              },
              "blade_pitch_deg": {
                "type": "number",
                "example": 4.2,
                "description": "Collective blade pitch angle in degrees."
              },
              "vibration_mm_s": {
                "type": "number",
                "example": 1.8,
                "description": "Nacelle vibration velocity in millimetres per second."
              },
              "error_code": {
                "type": "string",
                "nullable": true,
                "example": null,
                "description": "Active device error code, or null when the turbine reports no fault."
              }
            },
            "required": [
              "wind_speed_ms",
              "power_output_kw",
              "rotor_rpm",
              "gearbox_temp_c",
              "nacelle_direction_deg",
              "blade_pitch_deg",
              "vibration_mm_s",
              "error_code"
            ],
            "description": "Latest reported telemetry block."
          },
          "meta": {
            "type": "object",
            "properties": {
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "example": "2026-11-10T12:00:01.240Z",
                "description": "Server time at which the response was produced."
              }
            },
            "required": [
              "timestamp"
            ],
            "description": "Response metadata."
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "ReportedTelemetry": {
        "type": "object",
        "properties": {
          "wind_speed_ms": {
            "type": "number",
            "example": 8.4,
            "description": "Current measured wind speed in metres per second."
          },
          "power_output_kw": {
            "type": "number",
            "example": 3100,
            "description": "Current active power in kilowatts."
          },
          "rotor_rpm": {
            "type": "number",
            "example": 12.1,
            "description": "Rotor speed in revolutions per minute."
          },
          "gearbox_temp_c": {
            "type": "number",
            "example": 62.3,
            "description": "Gearbox oil temperature in degrees Celsius."
          },
          "nacelle_direction_deg": {
            "type": "number",
            "example": 245,
            "description": "Nacelle heading in degrees clockwise from north."
          },
          "blade_pitch_deg": {
            "type": "number",
            "example": 4.2,
            "description": "Collective blade pitch angle in degrees."
          },
          "vibration_mm_s": {
            "type": "number",
            "example": 1.8,
            "description": "Nacelle vibration velocity in millimetres per second."
          },
          "error_code": {
            "type": "string",
            "nullable": true,
            "example": null,
            "description": "Active device error code, or null when the turbine reports no fault."
          }
        },
        "required": [
          "wind_speed_ms",
          "power_output_kw",
          "rotor_rpm",
          "gearbox_temp_c",
          "nacelle_direction_deg",
          "blade_pitch_deg",
          "vibration_mm_s",
          "error_code"
        ]
      },
      "TurbineAlert": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "WIND_HIGH",
              "WIND_LOW",
              "GEARBOX_OVERHEAT",
              "VIBRATION_HIGH",
              "POWER_LIMITED",
              "OFFLINE",
              "ERROR_CODE"
            ],
            "example": "GEARBOX_OVERHEAT",
            "description": "Stable machine-readable alert code."
          },
          "severity": {
            "type": "string",
            "enum": [
              "info",
              "warning",
              "critical"
            ],
            "example": "critical",
            "description": "Alert severity: info, warning, or critical."
          },
          "message": {
            "type": "string",
            "example": "Gearbox temperature is above 80 C.",
            "description": "English diagnostic message."
          },
          "since": {
            "type": "string",
            "format": "date-time",
            "example": "2026-11-10T12:00:00.000Z",
            "description": "ISO 8601 timestamp of the transition into the active state."
          }
        },
        "required": [
          "code",
          "severity",
          "message",
          "since"
        ]
      },
      "TurbineIdParams": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "WT-001",
            "description": "Turbine identifier, for example WT-001."
          }
        },
        "required": [
          "id"
        ]
      },
      "TurbineListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "example": "WT-001",
                  "description": "Turbine identifier."
                },
                "model": {
                  "type": "string",
                  "example": "Vestas V150-4.2MW",
                  "description": "Turbine model."
                },
                "farm": {
                  "type": "string",
                  "example": "Mashhad Wind Farm",
                  "description": "Parent farm name."
                },
                "location": {
                  "type": "object",
                  "properties": {
                    "lat": {
                      "type": "number",
                      "example": 36.50135,
                      "description": "Latitude in decimal degrees."
                    },
                    "lon": {
                      "type": "number",
                      "example": 59.1982,
                      "description": "Longitude in decimal degrees."
                    }
                  },
                  "required": [
                    "lat",
                    "lon"
                  ],
                  "description": "Generator position."
                },
                "online": {
                  "type": "boolean",
                  "description": "Derived from the age of last_seen."
                },
                "firmware": {
                  "type": "string",
                  "example": "2.3.1",
                  "description": "Controller firmware version."
                },
                "reported": {
                  "type": "object",
                  "properties": {
                    "wind_speed_ms": {
                      "type": "number",
                      "example": 8.4,
                      "description": "Current measured wind speed in metres per second."
                    },
                    "power_output_kw": {
                      "type": "number",
                      "example": 3100,
                      "description": "Current active power in kilowatts."
                    },
                    "rotor_rpm": {
                      "type": "number",
                      "example": 12.1,
                      "description": "Rotor speed in revolutions per minute."
                    },
                    "gearbox_temp_c": {
                      "type": "number",
                      "example": 62.3,
                      "description": "Gearbox oil temperature in degrees Celsius."
                    },
                    "nacelle_direction_deg": {
                      "type": "number",
                      "example": 245,
                      "description": "Nacelle heading in degrees clockwise from north."
                    },
                    "blade_pitch_deg": {
                      "type": "number",
                      "example": 4.2,
                      "description": "Collective blade pitch angle in degrees."
                    },
                    "vibration_mm_s": {
                      "type": "number",
                      "example": 1.8,
                      "description": "Nacelle vibration velocity in millimetres per second."
                    },
                    "error_code": {
                      "type": "string",
                      "nullable": true,
                      "example": null,
                      "description": "Active device error code, or null when the turbine reports no fault."
                    }
                  },
                  "required": [
                    "wind_speed_ms",
                    "power_output_kw",
                    "rotor_rpm",
                    "gearbox_temp_c",
                    "nacelle_direction_deg",
                    "blade_pitch_deg",
                    "vibration_mm_s",
                    "error_code"
                  ],
                  "description": "Newest sample from the latest received report batch."
                },
                "desired": {
                  "type": "object",
                  "properties": {
                    "power_limit_kw": {
                      "type": "number",
                      "example": 4200,
                      "description": "Maximum allowed active power in kilowatts."
                    },
                    "cut_in_speed_ms": {
                      "type": "number",
                      "example": 3,
                      "description": "Wind speed at which generation starts, in metres per second."
                    },
                    "cut_out_speed_ms": {
                      "type": "number",
                      "example": 25,
                      "description": "Wind speed at which generation stops, in metres per second."
                    }
                  },
                  "required": [
                    "power_limit_kw",
                    "cut_in_speed_ms",
                    "cut_out_speed_ms"
                  ],
                  "description": "Read-only operating envelope. It is never writable through this API."
                },
                "last_seen": {
                  "type": "string",
                  "format": "date-time",
                  "example": "2026-11-10T12:00:00.000Z",
                  "description": "Time of the most recent successful report batch."
                }
              },
              "required": [
                "id",
                "model",
                "farm",
                "location",
                "online",
                "firmware",
                "reported",
                "desired",
                "last_seen"
              ]
            },
            "description": "Page of turbine twins."
          },
          "meta": {
            "type": "object",
            "properties": {
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "example": "2026-11-10T12:00:01.240Z",
                "description": "Server time at which the response was produced."
              },
              "page": {
                "type": "number",
                "example": 1,
                "description": "Current 1-based page."
              },
              "size": {
                "type": "number",
                "example": 20,
                "description": "Page size."
              },
              "total": {
                "type": "number",
                "example": 10,
                "description": "Total matching turbines."
              },
              "total_pages": {
                "type": "number",
                "example": 1,
                "description": "Total number of pages."
              }
            },
            "required": [
              "page",
              "size",
              "total",
              "total_pages"
            ],
            "description": "Pagination metadata."
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "TurbineResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "example": "WT-001",
                "description": "Turbine identifier."
              },
              "model": {
                "type": "string",
                "example": "Vestas V150-4.2MW",
                "description": "Turbine model."
              },
              "farm": {
                "type": "string",
                "example": "Mashhad Wind Farm",
                "description": "Parent farm name."
              },
              "location": {
                "type": "object",
                "properties": {
                  "lat": {
                    "type": "number",
                    "example": 36.50135,
                    "description": "Latitude in decimal degrees."
                  },
                  "lon": {
                    "type": "number",
                    "example": 59.1982,
                    "description": "Longitude in decimal degrees."
                  }
                },
                "required": [
                  "lat",
                  "lon"
                ],
                "description": "Generator position."
              },
              "online": {
                "type": "boolean",
                "description": "Derived from the age of last_seen."
              },
              "firmware": {
                "type": "string",
                "example": "2.3.1",
                "description": "Controller firmware version."
              },
              "reported": {
                "type": "object",
                "properties": {
                  "wind_speed_ms": {
                    "type": "number",
                    "example": 8.4,
                    "description": "Current measured wind speed in metres per second."
                  },
                  "power_output_kw": {
                    "type": "number",
                    "example": 3100,
                    "description": "Current active power in kilowatts."
                  },
                  "rotor_rpm": {
                    "type": "number",
                    "example": 12.1,
                    "description": "Rotor speed in revolutions per minute."
                  },
                  "gearbox_temp_c": {
                    "type": "number",
                    "example": 62.3,
                    "description": "Gearbox oil temperature in degrees Celsius."
                  },
                  "nacelle_direction_deg": {
                    "type": "number",
                    "example": 245,
                    "description": "Nacelle heading in degrees clockwise from north."
                  },
                  "blade_pitch_deg": {
                    "type": "number",
                    "example": 4.2,
                    "description": "Collective blade pitch angle in degrees."
                  },
                  "vibration_mm_s": {
                    "type": "number",
                    "example": 1.8,
                    "description": "Nacelle vibration velocity in millimetres per second."
                  },
                  "error_code": {
                    "type": "string",
                    "nullable": true,
                    "example": null,
                    "description": "Active device error code, or null when the turbine reports no fault."
                  }
                },
                "required": [
                  "wind_speed_ms",
                  "power_output_kw",
                  "rotor_rpm",
                  "gearbox_temp_c",
                  "nacelle_direction_deg",
                  "blade_pitch_deg",
                  "vibration_mm_s",
                  "error_code"
                ],
                "description": "Newest sample from the latest received report batch."
              },
              "desired": {
                "type": "object",
                "properties": {
                  "power_limit_kw": {
                    "type": "number",
                    "example": 4200,
                    "description": "Maximum allowed active power in kilowatts."
                  },
                  "cut_in_speed_ms": {
                    "type": "number",
                    "example": 3,
                    "description": "Wind speed at which generation starts, in metres per second."
                  },
                  "cut_out_speed_ms": {
                    "type": "number",
                    "example": 25,
                    "description": "Wind speed at which generation stops, in metres per second."
                  }
                },
                "required": [
                  "power_limit_kw",
                  "cut_in_speed_ms",
                  "cut_out_speed_ms"
                ],
                "description": "Read-only operating envelope. It is never writable through this API."
              },
              "last_seen": {
                "type": "string",
                "format": "date-time",
                "example": "2026-11-10T12:00:00.000Z",
                "description": "Time of the most recent successful report batch."
              }
            },
            "required": [
              "id",
              "model",
              "farm",
              "location",
              "online",
              "firmware",
              "reported",
              "desired",
              "last_seen"
            ],
            "description": "Full turbine twin."
          },
          "meta": {
            "type": "object",
            "properties": {
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "example": "2026-11-10T12:00:01.240Z",
                "description": "Server time at which the response was produced."
              }
            },
            "required": [
              "timestamp"
            ],
            "description": "Response metadata."
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "TurbinesQuery": {
        "type": "object",
        "properties": {
          "online": {
            "type": "boolean",
            "description": "Filter by derived online state. Use \"true\" or \"false\"."
          },
          "page": {
            "type": "number",
            "description": "1-based page number. Defaults to 1. Minimum 1."
          },
          "size": {
            "type": "number",
            "description": "Page size between 1 and 50. Defaults to 20."
          }
        }
      },
      "TurbineTwin": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "WT-001",
            "description": "Turbine identifier."
          },
          "model": {
            "type": "string",
            "example": "Vestas V150-4.2MW",
            "description": "Turbine model."
          },
          "farm": {
            "type": "string",
            "example": "Mashhad Wind Farm",
            "description": "Parent farm name."
          },
          "location": {
            "type": "object",
            "properties": {
              "lat": {
                "type": "number",
                "example": 36.50135,
                "description": "Latitude in decimal degrees."
              },
              "lon": {
                "type": "number",
                "example": 59.1982,
                "description": "Longitude in decimal degrees."
              }
            },
            "required": [
              "lat",
              "lon"
            ],
            "description": "Generator position."
          },
          "online": {
            "type": "boolean",
            "description": "Derived from the age of last_seen."
          },
          "firmware": {
            "type": "string",
            "example": "2.3.1",
            "description": "Controller firmware version."
          },
          "reported": {
            "type": "object",
            "properties": {
              "wind_speed_ms": {
                "type": "number",
                "example": 8.4,
                "description": "Current measured wind speed in metres per second."
              },
              "power_output_kw": {
                "type": "number",
                "example": 3100,
                "description": "Current active power in kilowatts."
              },
              "rotor_rpm": {
                "type": "number",
                "example": 12.1,
                "description": "Rotor speed in revolutions per minute."
              },
              "gearbox_temp_c": {
                "type": "number",
                "example": 62.3,
                "description": "Gearbox oil temperature in degrees Celsius."
              },
              "nacelle_direction_deg": {
                "type": "number",
                "example": 245,
                "description": "Nacelle heading in degrees clockwise from north."
              },
              "blade_pitch_deg": {
                "type": "number",
                "example": 4.2,
                "description": "Collective blade pitch angle in degrees."
              },
              "vibration_mm_s": {
                "type": "number",
                "example": 1.8,
                "description": "Nacelle vibration velocity in millimetres per second."
              },
              "error_code": {
                "type": "string",
                "nullable": true,
                "example": null,
                "description": "Active device error code, or null when the turbine reports no fault."
              }
            },
            "required": [
              "wind_speed_ms",
              "power_output_kw",
              "rotor_rpm",
              "gearbox_temp_c",
              "nacelle_direction_deg",
              "blade_pitch_deg",
              "vibration_mm_s",
              "error_code"
            ],
            "description": "Newest sample from the latest received report batch."
          },
          "desired": {
            "type": "object",
            "properties": {
              "power_limit_kw": {
                "type": "number",
                "example": 4200,
                "description": "Maximum allowed active power in kilowatts."
              },
              "cut_in_speed_ms": {
                "type": "number",
                "example": 3,
                "description": "Wind speed at which generation starts, in metres per second."
              },
              "cut_out_speed_ms": {
                "type": "number",
                "example": 25,
                "description": "Wind speed at which generation stops, in metres per second."
              }
            },
            "required": [
              "power_limit_kw",
              "cut_in_speed_ms",
              "cut_out_speed_ms"
            ],
            "description": "Read-only operating envelope. It is never writable through this API."
          },
          "last_seen": {
            "type": "string",
            "format": "date-time",
            "example": "2026-11-10T12:00:00.000Z",
            "description": "Time of the most recent successful report batch."
          }
        },
        "required": [
          "id",
          "model",
          "farm",
          "location",
          "online",
          "firmware",
          "reported",
          "desired",
          "last_seen"
        ]
      }
    },
    "responses": {}
  }
}
