{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://autoagentprotocol.org/v1.0/schemas/vehicle.schema.json",
  "title": "Vehicle",
  "description": "The single vehicle interface used everywhere a vehicle is referenced — inventory.search results, inventory.vehicle detail, vehicle_of_interest, and trade_in. v1.0 merges the former Vehicle + VehicleDetail split into one shape: there is now exactly one vehicle type.\n\nField semantics differ by context:\n- For inventory listings (inventory.search / inventory.vehicle) `condition` MUST be one of `new`, `used`, `cpo` and `status` MUST be one of `available`, `intransit`, `pending`. Pricing fields describe the dealer's listing.\n- For vehicle_of_interest, `condition` MUST be one of `new`, `used`, `cpo`.\n- For trade_in, `condition` MUST be one of `excellent`, `good`, `fair`, `poor`. Pricing fields are typically absent on the request side and may be populated by the dealer's appraisal response.\n\nAll prices are plain integers in whole US dollars (v1.0 dropped the nested {amount, currency} Money object). Context-dependent constraints are enforced at the using request/response schema. No fields are required at this base schema; `additionalProperties: true` lets inventory responses carry richer dealer-specific fields without schema changes.",
  "type": "object",
  "properties": {
    "vin": {
      "type": "string",
      "pattern": "^[A-HJ-NPR-Z0-9]{17}$",
      "description": "Vehicle Identification Number (17 chars, ISO 3779). Optional on trade-ins; recommended on inventory listings of used vehicles."
    },
    "year": {
      "type": "integer",
      "minimum": 1900,
      "maximum": 2100,
      "description": "Model year (e.g. 2024)."
    },
    "make": {
      "type": "string",
      "description": "Vehicle make / manufacturer brand (e.g. 'Honda', 'BMW', 'Ford')."
    },
    "model": {
      "type": "string",
      "description": "Vehicle model name (e.g. 'CR-V', '3 Series', 'F-150')."
    },
    "trim": {
      "type": "string",
      "description": "Trim level (e.g. 'EX-L', 'M Sport', 'Lariat')."
    },
    "condition": {
      "type": "string",
      "enum": ["new", "used", "cpo", "excellent", "good", "fair", "poor"],
      "description": "Combined condition enum spanning both sale-condition and trade-in-condition vocabularies. For inventory listings and vehicle_of_interest use one of `new` | `used` | `cpo` (Certified Pre-Owned). For trade_in use one of `excellent` | `good` | `fair` | `poor`. The using schema enforces the correct subset by context."
    },
    "status": {
      "type": "string",
      "enum": ["available", "intransit", "pending"],
      "description": "Inventory availability. v1.0 supports exactly three values: `available` (in stock now), `intransit` (allocated / en route to the dealership), `pending` (deal in progress). A vehicle in any other state is OUT OF STOCK and MUST NOT appear in inventory feeds — dealers omit it and buyer agents ignore any item missing or carrying an unknown status. Required on inventory listings; omitted on vehicle_of_interest and trade_in."
    },
    "rooftop": {
      "type": ["string", "null"],
      "description": "Which dealership location/rooftop holds this vehicle, identified by the rooftop's `name` from dealer.information. Nullable; single-rooftop dealers MAY leave it null."
    },
    "msrp": {
      "type": "integer",
      "minimum": 0,
      "description": "Manufacturer's Suggested Retail Price (sticker price), whole US dollars. Inventory context."
    },
    "price": {
      "type": "integer",
      "minimum": 0,
      "description": "FTC-emphasized FINAL out-the-door price after all incentives, mandatory fees, and required add-ons, in whole US dollars. Per FTC enforcement (CARS Rule), this field MUST reflect the total amount the buyer would pay; advertising a 'price' that excludes required fees or omits required add-ons is a violation. Inventory context."
    },
    "list_price": {
      "type": "integer",
      "minimum": 0,
      "description": "Dealer's advertised list price; the base price BEFORE incentives, taxes, or fees, in whole US dollars. Inventory context."
    },
    "offered_price": {
      "type": "integer",
      "minimum": 0,
      "description": "Regional price equal to list_price plus applicable taxes for the buyer's `zip`, in whole US dollars, when the dealer enables desking. Present only if a `zip` is supplied AND the dealer supports regional pricing. Inventory context."
    },
    "zip": {
      "type": "string",
      "pattern": "^\\d{5}(-\\d{4})?$",
      "description": "Buyer ZIP code used to compute regional pricing fields (`offered_price`). US ZIP, 5 digits or ZIP+4. Optional; when absent, regional pricing fields MUST be omitted."
    },
    "stock": {
      "type": "string",
      "description": "Dealer's stock number for this unit. Inventory and vehicle_of_interest contexts."
    },
    "dealer_id": {
      "type": "string",
      "description": "Stable identifier of the dealer that owns this listing. Inventory context."
    },
    "vehicle_id": {
      "type": "string",
      "description": "Dealer-internal identifier when the vehicle is not yet VIN-decoded (e.g. an in-transit unit)."
    },
    "mileage": {
      "type": "integer",
      "minimum": 0,
      "description": "Odometer reading in miles. Required for trade-ins; typical on used inventory."
    },
    "body": {
      "type": "string",
      "description": "Body style as text (e.g. 'sedan', 'suv', 'truck', 'coupe', 'hatchback', 'wagon', 'minivan', 'convertible')."
    },
    "transmission": {
      "type": "string",
      "description": "Transmission type as text (e.g. 'automatic', 'manual', '8-speed automatic', 'cvt')."
    },
    "driveline": {
      "type": "string",
      "description": "Drivetrain layout (e.g. 'fwd', 'rwd', 'awd', '4wd')."
    },
    "engine": {
      "type": "string",
      "description": "Engine description (e.g. '2.0L Turbo I4', '3.5L V6 Hybrid')."
    },
    "fuel": {
      "type": "string",
      "description": "Fuel type (e.g. 'gas', 'diesel', 'hybrid', 'phev', 'bev')."
    },
    "city_mpg": {
      "type": "integer",
      "minimum": 0,
      "description": "EPA city fuel-economy estimate in miles per gallon. Omit for fully electric vehicles (use `electric_range_mi`)."
    },
    "highway_mpg": {
      "type": "integer",
      "minimum": 0,
      "description": "EPA highway fuel-economy estimate in miles per gallon. Omit for fully electric vehicles (use `electric_range_mi`)."
    },
    "electric_range_mi": {
      "type": "number",
      "minimum": 0,
      "description": "Estimated electric range in miles, for BEV and PHEV vehicles."
    },
    "exterior_color": {
      "type": "string",
      "description": "Free-text exterior color name."
    },
    "interior_color": {
      "type": "string",
      "description": "Free-text interior color or upholstery name."
    },
    "features": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Notable equipment and options as free-text strings (e.g. 'Adaptive Cruise Control', 'Apple CarPlay', 'Heated Front Seats'). v1.0 uses one flat list and does not separate option packages, factory equipment, or installed accessories."
    },
    "photos": {
      "type": "array",
      "items": { "type": "string", "format": "uri" },
      "description": "Public URLs of vehicle photos, ordered by relevance."
    },
    "vdp_url": {
      "type": "string",
      "format": "uri",
      "description": "Public Vehicle Detail Page (VDP) URL on the dealer's website."
    },
    "description": {
      "type": "string",
      "description": "Human-readable description / dealer marketing copy."
    },
    "notes": {
      "type": "string",
      "description": "Dealer notes (e.g. 'recently arrived', 'service history available')."
    },
    "inventory_date": {
      "type": "string",
      "format": "date",
      "description": "Date (RFC 3339 full-date, e.g. '2026-04-21') the vehicle first appeared in the dealership's inventory."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 / RFC 3339 timestamp (with timezone offset) of the last update to this vehicle's availability, price, or status (e.g. '2026-04-30T08:42:00Z'). Buyer agents treat this as the freshness signal for availability claims."
    }
  },
  "additionalProperties": true
}