Open Vehicle Schema

JSON Schema

This section documents the OVS JSON schema structure and guiding principles.

Top-level structure

  • Year → Make → Model → Trim → Body → Engine → Transmission → Options
  • Deterministic identifiers (OVS IDs) are derived from canonicalized attribute sets.
  • Fields are explicit and typed; avoid ambiguous or overloaded fields.

Repo layout

  • Schemas: /schemas/vehicle.json, /schemas/engine.json, /schemas/transmission.json, /schemas/body.json
  • Dataset: /data/reference (current dataset), /data/YYYY (frozen releases), /data/latest (copy of latest)

Dataset files

Files are simple JSON arrays:

  • engines.json
  • transmissions.json
  • bodies.json
  • vehicles.json

Example (simplified)

{
  "year": 2024,
  "make": "Example",
  "model": "Alpha",
  "trim": "Base",
  "body": "Sedan",
  "engine": {
    "type": "I4",
    "displacementL": 2.0,
    "fuel": "Gasoline"
  },
  "transmission": {
    "type": "Automatic",
    "gears": 8
  },
  "options": ["Sunroof", "AWD"]
}

Validation

All records in the reference dataset must validate against the versioned JSON schema. CI pipelines enforce:

  • Schema validation
  • Deterministic ID stability
  • Backwards-compatible changes for minor/patch releases

Do not introduce fields derived from proprietary sources without open documentation and consensus.

Note: Examples on this site are illustrative.

← Back to Docs Hub