Contratto OpenAPI
Generate un client tipizzato nel vostro linguaggio dal documento OpenAPI, e validate le richieste rispetto a esso.
AVS, l'AutoUncle Vehicle Schema, è un JSON Schema aperto e versionato per descrivere un'auto: cos'è, come è costruita e come è equipaggiata. Usatelo nei vostri sistemi, validatelo in sette linguaggi e sviluppate su un'API che parla lo stesso modello di identità.
AVS ha due tipi di documento: un documento di tipo descrive un'auto così come è costruita, per esempio una BMW 320e G20 Sedan con M Sport; un documento di veicolo descrive una singola auto fisica di quel tipo, con il suo VIN, contachilometri, colore e storia. Con licenza Apache-2.0, senza dati di catalogo al suo interno.
AVS dice cos'è l'auto. Quanto vale e dove è in vendita appartengono ad altro.
Sono obbligatori solo marca e modello. Nulla viene indovinato, e l'assenza deve essere dichiarata.
Ogni record di catalogo elenca i suoi ID in qualsiasi schema, come AutoUncle, Wikidata o KBA HSN/TSN, e nessuno è privilegiato.
Le unità fanno parte dei nomi dei campi, i valori seguono il Certificato di conformità UE e la WLTP, e paesi, valute e VIN usano codici ISO.
{
"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"]
}
}
}
Marca, modello, generazione e fase, poi carrozzeria e motorizzazione come fatti indipendenti, e allestimento, pacchetti e optional per nome. Le nostre API identificano le auto lungo lo stesso percorso, da marca e modello a generazione, motorizzazione e allestimento, con ID stabili che potete salvare in AVS nello schema autouncle.
Ogni pacchetto include lo schema e un validatore che restituisce ogni errore con un JSON Pointer che lo localizza. Sono generati dallo schema, mai scritti a mano, e la loro versione coincide sempre con quella dello schema.
| Linguaggio | Pacchetto | Validazione |
|---|---|---|
| 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) |
Generate un client tipizzato nel vostro linguaggio dal documento OpenAPI, e validate le richieste rispetto a esso.
Gli errori sono documenti problem RFC 9457 con un codice stabile, un riferimento al campo e una correzione suggerita.
Paesi ISO 3166, valute ISO 4217 e VIN ISO 3779, nelle richieste e nei risultati.
Ogni valutazione accetta una chiave di idempotenza, così una richiesta ripetuta non viene mai addebitata due volte.
La stessa API come strumenti per agenti AI, più una skill di integrazione e llms.txt per gli assistenti di programmazione.
Leggete lo schema, generate un client dal contratto OpenAPI e valutate la vostra prima auto con una chiave di test gratuita.