https://github.com/maurocerrato/sovd-lab
YAML/JSON capability descriptions, /docs endpoint, OpenAPI specs. Shared with ride-sovd-gateway, diagnostics-standardization. MIT (code) + CC BY 4.0 (specs/docs)
https://github.com/maurocerrato/sovd-lab
diagnostics json openapi3 sovd standardization yaml
Last synced: 2 months ago
JSON representation
YAML/JSON capability descriptions, /docs endpoint, OpenAPI specs. Shared with ride-sovd-gateway, diagnostics-standardization. MIT (code) + CC BY 4.0 (specs/docs)
- Host: GitHub
- URL: https://github.com/maurocerrato/sovd-lab
- Owner: MauroCerrato
- License: other
- Created: 2025-08-06T12:28:59.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-09-03T13:40:52.000Z (10 months ago)
- Last Synced: 2025-09-03T15:28:00.400Z (10 months ago)
- Topics: diagnostics, json, openapi3, sovd, standardization, yaml
- Language: Python
- Homepage:
- Size: 11.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# SOVD-Lab
[](#)
**Mission:** Make SOVD practical, open, and reusable—without leaking IP.
This lab provides small, runnable diagnostics scenarios that align with:
- Eclipse **OpenSOVD** (Apache-2.0)
- Emerging **ISO 17978** standard
All content is **IP-safe**:
- Code: Apache-2.0
- Docs: CC BY 4.0
- Synthetic data: CC0
---
## 🚦 The VKO / HAAD Expansion (New!)
*Where Regulation meets Implementation.*
As of Dec 2025, `sovd-lab` includes a dedicated layer for **Vehicle Knowledge Officer (VKO)** workflows, focusing on **Highly Automated Autonomous Driving (HAAD)** compliance (UN R157, R155, R156).
I have decidedd on an **Additive Structure**: existing diagnostic services remain untouched, while new compliance artifacts map simulated events to regulatory obligations.
### 📂 Directory Structure for Compliance
* **`docs/haad/`**: The knowledge base with documentation.
* `action-packs/`: Regional guides (EU/CN/US) mapping Law to Code (e.g., *ALKS Essentials*).
* `checklist/`: a draft description of a DSSAD Minimal Record Set (ALKS-focused, synthetic).
* `compliance-mapping/`: JSON Schemas defining "Legal Events" (e.g., `controlTransition.schema.json`).
* `compliance-mapping/event-schemas/`: includes draft schemas of HAAD relevant events (e.g. MRM, control transition request).
* `compliance-mapping/evidence/`: will include synthetic trace logs proving compliance for simulated audits.
* **`services/kotlin-events/`**: A SOTIF-aware sentinel monitoring strictly for safety violations (Actuation Mismatches, illogical states).
---
---
## 🚀 Quick Start
### Option 1: REST Collections
Open `clients/rest-collections/sample.http` in VS Code (REST Client extension) and send requests.
### Option 2: CLI
```bash
python clients/cli/sovd_cli.py --host http://localhost:8080
```
### Option 3: Web Client
Open `clients/web/index.html` and invoke sample endpoints.
## Option4: 🐳 Multi-Node Diagnostics Simulation with Docker Compose
Run the full stack with Docker Compose:
```bash
git clone https://github.com/MauroCerrato/sovd-lab.git
cd sovd-lab
docker compose up --build
```
---
## 🧪 Architecture Diagram
The current diagnostics ecosystem using SOVD and OBD-II protocols is as of today realized in three services, 2 servers, 1 gateway and one client.
```code
+------------------+ +------------------+ +------------------+ +------------------+
| mock-sovd | <---> | gateway | <---> | obd2-sovd-sim | <---> | go-capabilities |
+------------------+ +------------------+ +------------------+ +------------------+
↑ ↑ ↑ ↑
| | | |
Docker Compose orchestrates all services with shared volumes and network, across Python and Go services
```
---
### 🔧 Services Overview
| Service | Port | Description |
|-------------------|------|----------------------------------------------------|
| mock-sovd | 8080 | SOVD mock server for synthetic vehicle data |
| gateway | 8081 | API gateway routing anonymized partner APIs |
| obd2-sovd-sim | 8083 | Simulated OBD-II server with SOVD-like endpoints |
| go-capabilities | 8085 | Overall vehicles healthcheck and YML capabilities |
### 🔁 Features
- ✅ Retry logic (2 attempts, 1.5s delay) for transient backend failures
- ✅ /health and /healthz endpoints for monitoring
- ✅ Aggregated SOVD capabilities description
- ✅ Error handling for unreachable or failing upstream services
### 📡 Example Requests
```bash
# SOVD entity list
curl http://localhost:8081/partner/quick-check
# OBD-II VIN
curl http://localhost:8083/vehicle-001/api/vin
# OBD-II DTCs
curl http://localhost:8083/vehicle-001/api/dtc
# Go service health
curl -s http://localhost:8085/healthz
curl -s http://localhost:8085/data/ident/vin
```
### 🔧 Error Scenarios
| Scenario | HTTP Status | Description |
|--------------------------------|-------------|--------------------------------------|
| SOVD API unreachable | 502 | Network or connection error |
| SOVD API returns error | 4xx/5xx | Propagated from upstream |
| Unexpected internal exception | 500 | Caught and logged |
How to simulate unreachable SOVD API:
```bash
docker stop sovd-lab_mock-sovd_1
curl http://localhost:8081/partner/quick-check
```
### 📡 Example expected error Response, in case the mock-sovd is still not available
```json
{
"detail": "Gateway error: ConnectTimeout"
}
```
To recover, restart the backend container:
```bash
docker restart sovd-lab_mock-sovd_1
```
📡 Gateway Health Check
```bash
request:
curl http://localhost:8081/health
```
Response example:
```json
{
"status": "ok",
"service": "gateway",
"version": "0.2"
}
```
---
## 📂 Folder structure
- `clients/` REST collections, CLI, and tiny web client
- `examples/` anonymized entities and workflows, includes SOVD to OBD2 server and client
- `specs/` OpenAPI overlays and JSON Schemas (non-normative)
- `tools/` mapping prototypes and validators
- `docs/` intros, quickstart, IP safety, standardization links, acronyms
- `data/` synthetic datasets only
- `services/` API gateway and mock-sovd server, NEW added go-capabilities
---
## ✅ KPIs
- Multi-client coverage (REST, CLI, web)
- Multi-language solution (Python, Kotlin, Rust, Go)
- No custom SOVD server/client beyond OpenSOVD
- Harmonization demos with anonymized content
- 100% SPDX headers; 0 license CI failures
- Time-to-first-response < 48h; ≥5 good-first-issues open
---
### 🔮 Next Goals
- Add retry/backoff improvements
- OpenTelemetry instrumentation
- Monitoring-first demo (time-series backend)
- More error scenarios