{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://autoagentprotocol.org/v3.0/schemas/facets.schema.json",
  "title": "Facets",
  "description": "Counts and ranges across the full matching inventory, before pagination. Shared by inventory.facets and optional search-response facets on every binding. Omitted facets are unavailable; zero counts describe known empty buckets. Feature counts use verified present equipment only.",
  "type": "object",
  "$defs": {
    "term_facet": {
      "type": "array",
      "description": "A term facet: each entry pairs a distinct field value with the count of matching vehicles.",
      "examples": [[{ "value": "Honda", "count": 42 }, { "value": "Toyota", "count": 31 }]],
      "items": {
        "type": "object",
        "properties": {
          "value": {"type": ["string", "integer", "boolean"], "description": "A distinct value observed for this field across the matching set (e.g. a make, model, year or DC fast-charge boolean).", "examples": ["Honda", 2024, true]},
          "count": { "type": "integer", "minimum": 0, "description": "Number of matching vehicles carrying this value.", "examples": [42] }
        },
        "required": ["value", "count"],
        "additionalProperties": false
      }
    },
    "range_facet": {
      "type": "object",
      "description": "A numeric range facet: the observed min and max for a field across the matching set.",
      "examples": [{ "min": 18995, "max": 64995 }],
      "properties": {
        "min": { "type": "number", "description": "Lowest observed value for this field across the matching set.", "examples": [18995] },
        "max": { "type": "number", "description": "Highest observed value for this field across the matching set.", "examples": [64995] }
      },
      "required": ["min", "max"],
      "additionalProperties": false
    }
  },
  "properties": {
    "makes": { "$ref": "#/$defs/term_facet" },
    "models": { "$ref": "#/$defs/term_facet" },
    "trims": { "$ref": "#/$defs/term_facet" },
    "years": { "$ref": "#/$defs/term_facet" },
    "conditions": { "$ref": "#/$defs/term_facet" },
    "transmissions": { "$ref": "#/$defs/term_facet" },
    "fuels": { "$ref": "#/$defs/term_facet" },
    "dc_fast_charge": { "$ref": "#/$defs/term_facet", "description": "DC-fast-charge support facets (true/false counts), matching `Vehicle.dc_fast_charge` and `filters.dc_fast_charge`." },
    "charge_ports": { "$ref": "#/$defs/term_facet", "description": "EV charge/plug connector facets (e.g. `nacs`, `ccs`, `j1772`), matching `Vehicle.charge_port` and `filters.charge_port`." },
    "drivelines": { "$ref": "#/$defs/term_facet", "description": "Drivetrain-layout facets, matching `Vehicle.driveline` and `filters.driveline` (car context)." },
    "bodies": { "$ref": "#/$defs/term_facet", "description": "Body-style / segment facets, matching the `body` field on Vehicle and `filters.body` on InventorySearchRequest. Covers car body styles (e.g. 'sedan', 'suv') and motorcycle segments (e.g. 'cruiser', 'touring') alike." },
    "vehicle_types": { "$ref": "#/$defs/term_facet", "description": "Vehicle-type facets, matching `Vehicle.vehicle_type` and `filters.vehicle_type` (e.g. `car`, `motorcycle`)." },
    "exterior_colors": { "$ref": "#/$defs/term_facet" },
    "interior_colors": { "$ref": "#/$defs/term_facet" },
    "rooftops": { "$ref": "#/$defs/term_facet", "description": "Rooftop facets — vehicle counts per dealership location, matching `Vehicle.rooftop` and `filters.rooftops`." },
    "statuses": { "$ref": "#/$defs/term_facet" },
    "price_range": { "$ref": "#/$defs/range_facet", "description": "Observed minimum and maximum of authoritative Vehicle.price values. Vehicles without `price` do not contribute; omit `price_range` when no matching vehicle has `price`." },
    "mileage_range": { "$ref": "#/$defs/range_facet" },
    "year_range": { "$ref": "#/$defs/range_facet" },
    "displacement_cc_range": { "$ref": "#/$defs/range_facet", "description": "Engine-displacement range in cc across the matching set, matching `Vehicle.displacement_cc` and `filters.displacement_cc_min` / `filters.displacement_cc_max`." },
    "electric_range_mi_range": { "$ref": "#/$defs/range_facet", "description": "Electric-range span in miles across the matching set, matching `Vehicle.electric_range_mi` and `filters.electric_range_mi_min` / `filters.electric_range_mi_max`." },
    "features": {
      "type": "array",
      "description": "Advertised feature vocabulary and verified present counts. A code has one meaning across the deployment; unknown codes return UNSUPPORTED_FILTER. Counts exclude absent and unknown equipment.",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]*$",
            "maxLength": 80
          },
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "pattern": "\\S"
          },
          "count": {
            "type": "integer",
            "minimum": 0
          }
        },
        "required": [
          "code",
          "label",
          "count"
        ],
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}