{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://raw.githubusercontent.com/api-evangelist/marketcheck/main/json-schema/marketcheck-search-response.json",
  "title": "MarketCheck Search Response",
  "description": "Response object from the MarketCheck Cars API search endpoint",
  "type": "object",
  "properties": {
    "num_found": {
      "type": "integer",
      "description": "Total number of listings found matching the search criteria",
      "minimum": 0
    },
    "listings": {
      "type": "array",
      "description": "Array of vehicle listings matching the search criteria",
      "items": {
        "$ref": "marketcheck-listing.json"
      }
    },
    "stats": {
      "type": "object",
      "description": "Statistical aggregates for the search result set (when stats parameter is provided)",
      "properties": {
        "price": {
          "$ref": "#/definitions/StatField"
        },
        "miles": {
          "$ref": "#/definitions/StatField"
        },
        "msrp": {
          "$ref": "#/definitions/StatField"
        },
        "dom": {
          "$ref": "#/definitions/StatField"
        }
      }
    },
    "facets": {
      "type": "object",
      "description": "Facets for drilling down into the search results (when facets parameter is provided)",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "item": {
              "type": "string",
              "description": "Facet value"
            },
            "count": {
              "type": "integer",
              "description": "Number of listings with this facet value"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "StatField": {
      "type": "object",
      "description": "Statistical aggregates for a numeric field",
      "properties": {
        "mean": {
          "type": "number",
          "description": "Mean (average) value"
        },
        "min": {
          "type": "number",
          "description": "Minimum value"
        },
        "max": {
          "type": "number",
          "description": "Maximum value"
        },
        "count": {
          "type": "integer",
          "description": "Count of listings used to calculate stats"
        }
      }
    }
  }
}