{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://autoagentprotocol.org/v1.1/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",
  "examples": [
    {
      "vin": "1HGCV1F30NA123456",
      "year": 2024,
      "make": "Honda",
      "model": "CR-V",
      "trim": "EX-L",
      "condition": "new",
      "status": "available",
      "msrp": 36000,
      "price": 35500,
      "mileage": 12,
      "body": "suv",
      "exterior_color": "Crystal Black Pearl",
      "stock": "H12345"
    }
  ],
  "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.",
      "examples": ["1HGCV1F30NA123456"]
    },
    "year": {
      "type": "integer",
      "minimum": 1900,
      "maximum": 2100,
      "description": "Model year (e.g. 2024).",
      "examples": [2024]
    },
    "make": {
      "type": "string",
      "description": "Vehicle make / manufacturer brand (e.g. 'Honda', 'BMW', 'Ford').",
      "examples": ["Honda", "BMW", "Ford"]
    },
    "model": {
      "type": "string",
      "description": "Vehicle model name (e.g. 'CR-V', '3 Series', 'F-150').",
      "examples": ["CR-V", "3 Series", "F-150"]
    },
    "trim": {
      "type": "string",
      "description": "Trim level (e.g. 'EX-L', 'M Sport', 'Lariat').",
      "examples": ["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.",
      "examples": ["new", "used", "cpo"]
    },
    "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.",
      "examples": ["available", "intransit"]
    },
    "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.",
      "examples": ["Demo Toyota San Francisco"]
    },
    "msrp": {
      "type": "integer",
      "minimum": 0,
      "description": "Manufacturer's Suggested Retail Price (sticker price), whole US dollars. Inventory context.",
      "examples": [36000]
    },
    "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.",
      "examples": [35500]
    },
    "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.",
      "examples": [34000]
    },
    "stock": {
      "type": "string",
      "description": "Dealer's stock number for this unit. Inventory and vehicle_of_interest contexts.",
      "examples": ["H12345"]
    },
    "dealer_id": {
      "type": "string",
      "description": "Stable identifier of the dealer that owns this listing. Inventory context.",
      "examples": ["demo-toyota-sf"]
    },
    "vehicle_id": {
      "type": "string",
      "description": "Dealer-internal identifier when the vehicle is not yet VIN-decoded (e.g. an in-transit unit).",
      "examples": ["veh_8f3c1a"]
    },
    "mileage": {
      "type": "integer",
      "minimum": 0,
      "description": "Odometer reading in miles. Required for trade-ins; typical on used inventory.",
      "examples": [12, 38450]
    },
    "body": {
      "type": "string",
      "description": "Body style as text (e.g. 'sedan', 'suv', 'truck', 'coupe', 'hatchback', 'wagon', 'minivan', 'convertible').",
      "examples": ["suv", "sedan", "truck"]
    },
    "transmission": {
      "type": "string",
      "description": "Transmission type as text (e.g. 'automatic', 'manual', '8-speed automatic', 'cvt').",
      "examples": ["automatic", "cvt"]
    },
    "driveline": {
      "type": "string",
      "description": "Drivetrain layout (e.g. 'fwd', 'rwd', 'awd', '4wd').",
      "examples": ["awd", "fwd"]
    },
    "engine": {
      "type": "string",
      "description": "Engine description (e.g. '2.0L Turbo I4', '3.5L V6 Hybrid').",
      "examples": ["1.5L Turbo I4", "3.5L V6 Hybrid"]
    },
    "fuel": {
      "type": "string",
      "description": "Fuel type (e.g. 'gas', 'diesel', 'hybrid', 'phev', 'bev').",
      "examples": ["gas", "hybrid", "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`).",
      "examples": [28]
    },
    "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`).",
      "examples": [34]
    },
    "electric_range_mi": {
      "type": "number",
      "minimum": 0,
      "description": "Estimated electric range in miles, for BEV and PHEV vehicles.",
      "examples": [300]
    },
    "exterior_color": {
      "type": "string",
      "description": "Free-text exterior color name.",
      "examples": ["Crystal Black Pearl", "Platinum White Pearl"]
    },
    "interior_color": {
      "type": "string",
      "description": "Free-text interior color or upholstery name.",
      "examples": ["Black Leather", "Gray Cloth"]
    },
    "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.",
      "examples": [["Adaptive Cruise Control", "Apple CarPlay", "Heated Front Seats"]]
    },
    "photos": {
      "type": "array",
      "items": { "type": "string", "format": "uri" },
      "description": "Public URLs of vehicle photos, ordered by relevance.",
      "examples": [["https://cdn.example.com/vehicles/h12345/1.jpg", "https://cdn.example.com/vehicles/h12345/2.jpg"]]
    },
    "vdp_url": {
      "type": "string",
      "format": "uri",
      "description": "Public Vehicle Detail Page (VDP) URL on the dealer's website.",
      "examples": ["https://www.example.com/inventory/h12345"]
    },
    "description": {
      "type": "string",
      "description": "Human-readable description / dealer marketing copy.",
      "examples": ["Well-equipped EX-L with leather seating and a clean history report."]
    },
    "notes": {
      "type": "string",
      "description": "Dealer notes (e.g. 'recently arrived', 'service history available').",
      "examples": ["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.",
      "examples": ["2026-04-21"]
    },
    "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.",
      "examples": ["2026-04-30T08:42:00Z"]
    }
  },
  "additionalProperties": true
}