# =============================================================================
# FICTIONAL training API. Represents an EXTERNAL government registry whose
# conventions differ from ours on purpose: snake_case names, lowercase enums,
# dotted date format, API-key auth. Used for the data mapping exercise (D3).
# =============================================================================
openapi: 3.0.3
info:
  title: National Vehicle Registry API
  version: 2.0.1
  description: |
    Public vehicle data lookup by registration number (fictional).
    Note: dates are strings in DD.MM.YYYY format (registry legacy convention).
  contact:
    name: Registry Service Desk (fictional)
    email: support@vehreg.example
servers:
  - url: https://api.vehreg.example/v2
    description: Production (fictional)

security:
  - ApiKeyAuth: []

paths:
  /vehicles/{reg_number}:
    get:
      summary: Get vehicle record by registration number
      operationId: get_vehicle
      parameters:
        - name: reg_number
          in: path
          required: true
          description: Registration (licence plate) number, no spaces.
          schema:
            type: string
            example: "JK8472"
      responses:
        '200':
          description: Vehicle record found.
          headers:
            X-RateLimit-Remaining:
              description: Requests left in the current window (100/min per key).
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/vehicle_record'
              example:
                reg_number: "JK8472"
                vin_code: "WVWZZZ1JZXW000341"
                make: "Volkswagen"
                model: "Golf"
                first_reg_date: "14.03.2019"
                engine_capacity_ccm: 1395
                fuel_type: "petrol"
                color: "grey"
                owner_type: "private"
                inspection_valid_to: "11.04.2027"
                status: "registered"
        '401':
          description: Missing or invalid API key.
        '404':
          description: No vehicle with this registration number.
        '429':
          description: Rate limit exceeded (100 requests/minute per API key). Retry later.

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Static key issued per consuming organisation.

  schemas:
    vehicle_record:
      type: object
      required: [reg_number, make, model, first_reg_date, status]
      properties:
        reg_number:
          type: string
        vin_code:
          type: string
          description: May be absent for vehicles registered before 1995.
        make:
          type: string
        model:
          type: string
        first_reg_date:
          type: string
          description: First registration date, format DD.MM.YYYY (string, not ISO).
          example: "14.03.2019"
        engine_capacity_ccm:
          type: integer
          description: Engine displacement in cubic centimetres. Absent for electric.
        fuel_type:
          type: string
          enum: [petrol, diesel, electric, hybrid, gas, other]
        color:
          type: string
        owner_type:
          type: string
          enum: [private, company]
        inspection_valid_to:
          type: string
          description: Technical inspection valid until, DD.MM.YYYY. May be in the past.
        status:
          type: string
          description: registered = normal; stolen = flagged stolen (relevant for THEFT claims!)
          enum: [registered, deregistered, stolen]