Python

Updated Nov 4, 2026

Installation

pip install cardealer fairspec-metadata

Publication

import json

from cardealer import VERSION, Dataset

dataset = Dataset.model_validate(
    {
        "$schema": f"https://datisthq.github.io/cardealer/profiles/{VERSION}/dataset.json",
        "resources": [
            {
                "name": "dealer",
                "tableSchema": f"https://datisthq.github.io/cardealer/schemas/{VERSION}/dealer.json",
                "data": [
                    {
                        "title": "Premium Auto Sales",
                        "country": "United States",
                        "region": "California",
                        "city": "Los Angeles",
                        "address": "1234 Sunset Boulevard",
                        "postcode": "90028",
                        "phone": "+1-323-555-0100",
                        "email": "sales@premiumauto.com",
                        "url": "https://www.premiumauto.com",
                        "lat": 34.0983,
                        "lon": -118.3267,
                    }
                ],
            },
            {
                "name": "facility",
                "tableSchema": f"https://datisthq.github.io/cardealer/schemas/{VERSION}/facility.json",
                "data": [
                    {
                        "id": "showroom-la",
                        "type": "showroom",
                        "title": "Sunset Showroom",
                        "country": "United States",
                        "region": "California",
                        "city": "Los Angeles",
                        "address": "1234 Sunset Boulevard",
                    }
                ],
            },
        ],
    }
)

with open("dataset.json", "w") as file:
    json.dump(dataset.model_dump(mode="json", by_alias=True, exclude_none=True), file, indent=2)

Validation and consumption

import json

from cardealer import Dataset

with open("dataset.json") as file:
    dataset = Dataset.model_validate(json.load(file))
print(dataset)

Rows

Every row model is a pydantic model, so a single row validates on its own. Read rows by their JSON names (facilityId); the attributes use snake case (facility_id):

from cardealer import Car

car = Car.model_validate(
    {
        "facilityId": "showroom-la",
        "title": "BMW 3 Series 320d",
        "url": "https://www.premiumauto.com/cars/bmw-320d",
        "price": 32500,
        "currency": "USD",
        "mileage": 41000,
        "brand": "BMW",
        "model": "3 Series",
        "version": "320d",
        "fuel": "diesel",
        "gearbox": "auto",
        "category": "saloon",
        "color": "black",
        "door": "fourfive",
    }
)
print(car.facility_id)

Errors

A failed validation raises pydantic's ValidationError, which lists every problem with its location:

from pydantic import ValidationError

from cardealer import Dataset

try:
    Dataset.model_validate({"resources": []})
except ValidationError as error:
    for issue in error.errors():
        print(issue["loc"], issue["msg"])

Types

The enumerations are Literal types, so plain strings type-check and typing.get_args lists the values:

from typing import get_args

from cardealer import Fuel

fuels = get_args(Fuel)

Dump with by_alias=True to get the JSON names back, and exclude_none=True so that unset optional columns are left out rather than written as null, which the standard rejects. Unknown keys are kept.