{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/carstat-app/json-schema/carstat-app-search-results-response-schema.json",
  "title": "search_results_response",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/carstat-app-vehicle-specifications-api-openapi.yml#/components/schemas/search_results_response",
  "type": "object",
  "properties": {
    "metric": {
      "type": "string",
      "description": "The metric used for ranking. Available metrics and their data sources:\n- `horsepower` — total system power (hp) for electrified vehicles; engine hp for ICE; summed motor output when no aggregate is available. Default order: desc.\n- `torque` — total system torque (Nm) for electrified vehicles; engine torque for ICE; summed motor output when no aggregate is available. Default order: desc.\n- `mpg` — combined US mpg from the available test cycle (combined, WLTC, EPA, CLTC, NEDC-equivalent, or NEDC); falls back to extra-urban mpg or EV MPGe. Default order: desc.\n- `acceleration` — 0–100 km/h time in seconds. Default order: asc (faster = lower).\n- `max_speed` — top speed in km/h. Default order: desc.\n- `curb_weight` — kerb weight in kg. Default order: asc (lighter = lower).\n- `cargo` — maximum trunk/boot volume in litres. Default order: desc.",
      "enum": [
        "horsepower",
        "torque",
        "mpg",
        "acceleration",
        "max_speed",
        "curb_weight",
        "cargo"
      ]
    },
    "order": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "description": "Sort order applied"
    },
    "total_matching": {
      "type": "integer",
      "description": "Total vehicles matching the filters (before limit)"
    },
    "showing": {
      "type": "integer",
      "description": "Number of results returned"
    },
    "results": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/search_result_item"
      }
    }
  },
  "required": [
    "metric",
    "order",
    "total_matching",
    "showing",
    "results"
  ],
  "$defs": {
    "search_result_item": {
      "type": "object",
      "description": "A single vehicle result from the search endpoint",
      "properties": {
        "modification_id": {
          "type": "string",
          "format": "uuid",
          "description": "Unique modification identifier"
        },
        "name": {
          "type": "string",
          "description": "Engine/powertrain configuration name"
        },
        "year_start": {
          "type": "integer",
          "description": "First model year this configuration was available"
        },
        "year_end": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Last confirmed production year; null when no final year is available"
        },
        "make": {
          "type": "string",
          "description": "Manufacturer name"
        },
        "model": {
          "type": "string",
          "description": "Model name"
        },
        "generation": {
          "type": [
            "string",
            "null"
          ],
          "description": "Vehicle generation name"
        },
        "model_year": {
          "type": "integer",
          "deprecated": true,
          "description": "Deprecated compatibility alias for year_start"
        },
        "body_type": {
          "type": [
            "string",
            "null"
          ],
          "description": "Body type(s), comma-separated when multiple (e.g. 'sedan', 'suv, crossover')"
        }
      },
      "additionalProperties": true
    }
  }
}