OpenAPI contract
Generate a typed client in your language from the OpenAPI document, and validate requests against it.
OPEN STANDARDS
One way to describe a car.
Open to everyone.
AVS, the AutoUncle Vehicle Schema, is an open, versioned JSON Schema for describing a car: what it is, how it is built and what it is equipped with. Use it in your own systems, validate it in seven languages, and build on an API that speaks the same identity model.
AVS · AUTOUNCLE VEHICLE SCHEMA
Facts only.
Every level a separate fact.
AVS has two kinds of document: a type document describes a car as built, such as a BMW 320e G20 Sedan with M Sport; a vehicle document describes one physical car of that type, with its VIN, odometer, colour and history. Licensed under Apache-2.0, with no catalogue data inside.
Facts, not opinions
AVS says what the car is. What it is worth and where it is for sale belong elsewhere.
Unknown is left out
Only brand and model are required. Nothing is guessed, and absence must be stated.
Any code system
Every catalogue record lists its IDs in any scheme, such as AutoUncle, Wikidata or KBA HSN/TSN, and none is privileged.
EU conventions
Units are part of field names, values follow the EU Certificate of Conformity and WLTP, and countries, currencies and VINs use ISO codes.
examples/type-bmw-320e-g20-m-sport.json
{
"avs": { "version": "0.3", "kind": "type" },
"identity": {
"brand": {
"name": "BMW",
"ids": [
{ "scheme": "autouncle", "value": "b-example0001" },
{ "scheme": "wikidata", "value": "Q26678" }
]
},
"model": {
"name": "3 Series",
"localNames": { "DK": "3-serie" }
},
"generation": { "name": "3 Series (G20/G21)", "code": "G20" },
"drivetrain": {
"name": "320e (204 Hp) Plug-in Hybrid Steptronic"
}
},
"specification": {
"powertrain": {
"energy": ["petrol", "electricity"],
"electrification": "phev",
"powerKw": 150, "torqueNm": 300
}
},
"equipment": {
"trim": {
"name": "M Sport",
"variations": ["M Sportpakke", "M-Sport"]
}
}
}THE IDENTITY MODEL
The same structure
our API resolves to.
Brand, model, generation and phase, then body and drivetrain as independent facts, and the trim, packages and options by name. Our APIs identify cars along the same path, from brand and model to generation, drivetrain and trim, with stable IDs you can store in AVS under the autouncle scheme.
VALIDATORS
Validate AVS
in seven languages.
Each package bundles the schema and a validator that returns every error with a JSON Pointer to it. They are generated from the schema, never hand-written, and their version always equals the schema's.
| Language | Package | Validate |
|---|---|---|
| Ruby | autouncle-avs | AVS.validate(doc) |
| TypeScript / JavaScript | @autouncle/avs | validate(doc) |
| Python | autouncle-avs | avs.validate(doc) |
| Go | github.com/AutoUncle/avs/packages/go | avs.Validate(b) |
| Java / JVM | com.autouncle:avs | Avs.validate(json) |
| .NET | AutoUncle.Avs | AvsSchema.Validate(json) |
| PHP | autouncle/avs | Avs::validate($doc) |
THE API
Standards all the way
down the API.
Problem details
Errors are RFC 9457 problem documents with a stable code, a pointer to the field and a suggested fix.
ISO codes
ISO 3166 countries, ISO 4217 currencies and ISO 3779 VINs, in requests and results.
Idempotent by design
Every valuation takes an idempotency key, so a retried request is never charged twice.
MCP for agents
The same API as tools for AI agents, plus an integration skill and llms.txt for coding assistants.
BUILD ON IT
Describe cars once.
Use them everywhere.
Read the schema, generate a client from the OpenAPI contract, and value your first car with a free test key.