{"id":30770249,"url":"https://github.com/maurocerrato/sovd-lab","last_synced_at":"2026-04-13T17:31:44.702Z","repository":{"id":308541967,"uuid":"1033185193","full_name":"MauroCerrato/sovd-lab","owner":"MauroCerrato","description":"YAML/JSON capability descriptions, /docs endpoint, OpenAPI specs. Shared with ride-sovd-gateway, diagnostics-standardization. MIT (code) + CC BY 4.0 (specs/docs)","archived":false,"fork":false,"pushed_at":"2025-09-03T13:40:52.000Z","size":12,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-03T15:28:00.400Z","etag":null,"topics":["diagnostics","json","openapi3","sovd","standardization","yaml"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MauroCerrato.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-06T12:28:59.000Z","updated_at":"2025-09-03T13:40:56.000Z","dependencies_parsed_at":"2025-08-26T21:22:03.875Z","dependency_job_id":"d626bb1e-2048-4d37-a7a7-1a3ed0aa9055","html_url":"https://github.com/MauroCerrato/sovd-lab","commit_stats":null,"previous_names":["maurocerrato/sovd-api-design","maurocerrato/sovd-lab"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MauroCerrato/sovd-lab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MauroCerrato%2Fsovd-lab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MauroCerrato%2Fsovd-lab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MauroCerrato%2Fsovd-lab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MauroCerrato%2Fsovd-lab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MauroCerrato","download_url":"https://codeload.github.com/MauroCerrato/sovd-lab/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MauroCerrato%2Fsovd-lab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273685604,"owners_count":25149722,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-04T02:00:08.968Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["diagnostics","json","openapi3","sovd","standardization","yaml"],"created_at":"2025-09-04T23:03:27.475Z","updated_at":"2026-04-13T17:31:44.695Z","avatar_url":"https://github.com/MauroCerrato.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SOVD-Lab\n[![CI status](https://img.shields.io/badge/CI-pending-lightgrey.svg)](#)\n\n**Mission:** Make SOVD practical, open, and reusable—without leaking IP.\n\nThis lab provides small, runnable diagnostics scenarios that align with:\n-  Eclipse **OpenSOVD** (Apache-2.0)\n- Emerging **ISO 17978** standard \n\nAll content is **IP-safe**:\n- Code: Apache-2.0\n- Docs: CC BY 4.0\n- Synthetic data: CC0\n\n---\n\n## 🚦 The VKO / HAAD Expansion (New!)\n*Where Regulation meets Implementation.*\n\nAs 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).\n\nI have decidedd on an **Additive Structure**: existing diagnostic services remain untouched, while new compliance artifacts map simulated events to regulatory obligations.\n\n### 📂 Directory Structure for Compliance\n* **`docs/haad/`**: The knowledge base with documentation.\n    * `action-packs/`: Regional guides (EU/CN/US) mapping Law to Code (e.g., *ALKS Essentials*).\n    * `checklist/`: a draft description of a DSSAD Minimal Record Set (ALKS-focused, synthetic).\n\t* `compliance-mapping/`: JSON Schemas defining \"Legal Events\" (e.g., `controlTransition.schema.json`).\n    * `compliance-mapping/event-schemas/`: includes draft schemas of HAAD relevant events (e.g. MRM, control transition request).\n\t* `compliance-mapping/evidence/`: will include synthetic trace logs proving compliance for simulated audits.\n* **`services/kotlin-events/`**: A SOTIF-aware sentinel monitoring strictly for safety violations (Actuation Mismatches, illogical states).\n\n---\n\n\n---\n\n## 🚀 Quick Start\n\n### Option 1: REST Collections\nOpen `clients/rest-collections/sample.http` in VS Code (REST Client extension) and send requests.\n\n### Option 2: CLI\n```bash\npython clients/cli/sovd_cli.py --host http://localhost:8080\n```\n\n### Option 3: Web Client\nOpen `clients/web/index.html` and invoke sample endpoints.\n\n\n## Option4: 🐳 Multi-Node Diagnostics Simulation with Docker Compose\n\nRun the full stack with Docker Compose:\n```bash\ngit clone https://github.com/MauroCerrato/sovd-lab.git\ncd sovd-lab\ndocker compose up --build\n```\n\n---\n\n## 🧪 Architecture Diagram\nThe current diagnostics ecosystem using SOVD and OBD-II protocols is as of today realized in three services, 2 servers, 1 gateway and one client.\n\n```code\n+------------------+       +------------------+       +------------------+       +------------------+\n|  mock-sovd       | \u003c---\u003e |  gateway         | \u003c---\u003e |  obd2-sovd-sim   | \u003c---\u003e |  go-capabilities |\n+------------------+       +------------------+       +------------------+       +------------------+\n        ↑                        ↑                          ↑                          ↑\n        |                        |                          |                          |\n    Docker Compose orchestrates all services with shared volumes and network, across Python and Go services\n```\n\n---\n\n### 🔧 Services Overview\n\n| Service           | Port | Description                                        |\n|-------------------|------|----------------------------------------------------|\n| mock-sovd         | 8080 | SOVD mock server for synthetic vehicle data        |\n| gateway           | 8081 | API gateway routing anonymized partner APIs        |\n| obd2-sovd-sim     | 8083 | Simulated OBD-II server with SOVD-like endpoints   |\n| go-capabilities   | 8085 | Overall vehicles healthcheck and YML capabilities  |\n\n\n### 🔁 Features\n\n- ✅ Retry logic (2 attempts, 1.5s delay) for transient backend failures\n- ✅ /health and /healthz endpoints for monitoring\n- ✅ Aggregated SOVD capabilities description\n- ✅ Error handling for unreachable or failing upstream services\n\n### 📡 Example Requests\n```bash\n# SOVD entity list\ncurl http://localhost:8081/partner/quick-check\n\n# OBD-II VIN\ncurl http://localhost:8083/vehicle-001/api/vin\n\n# OBD-II DTCs\ncurl http://localhost:8083/vehicle-001/api/dtc\n\n# Go service health\ncurl -s http://localhost:8085/healthz\ncurl -s http://localhost:8085/data/ident/vin\n```\n\n### 🔧 Error Scenarios\n\n| Scenario                        | HTTP Status | Description                         |\n|--------------------------------|-------------|--------------------------------------|\n| SOVD API unreachable           | 502         | Network or connection error          |\n| SOVD API returns error         | 4xx/5xx     | Propagated from upstream             |\n| Unexpected internal exception  | 500         | Caught and logged                    |\n\nHow to simulate unreachable SOVD API:\n```bash\ndocker stop sovd-lab_mock-sovd_1\ncurl http://localhost:8081/partner/quick-check\n```\n\n### 📡 Example expected error Response, in case the mock-sovd is still not available\n\n```json\n{\n  \"detail\": \"Gateway error: ConnectTimeout\"\n}\n```\n\nTo recover, restart the backend container:\n```bash\ndocker restart sovd-lab_mock-sovd_1\n```\n\n📡 Gateway Health Check\n\n```bash\nrequest:\ncurl http://localhost:8081/health\n```\n\nResponse example:\n```json\n{\n  \"status\": \"ok\",\n  \"service\": \"gateway\",\n  \"version\": \"0.2\"\n}\n```\n\n---\n\n## 📂 Folder structure\n- `clients/` REST collections, CLI, and tiny web client\n- `examples/` anonymized entities and workflows, includes SOVD to OBD2 server and client\n- `specs/` OpenAPI overlays and JSON Schemas (non-normative)\n- `tools/` mapping prototypes and validators\n- `docs/` intros, quickstart, IP safety, standardization links, acronyms\n- `data/` synthetic datasets only\n- `services/` API gateway and mock-sovd server, NEW added go-capabilities\n\n---\n\n## ✅ KPIs\n- Multi-client coverage (REST, CLI, web)\n- Multi-language solution (Python, Kotlin, Rust, Go)\n- No custom SOVD server/client beyond OpenSOVD\n- Harmonization demos with anonymized content\n- 100% SPDX headers; 0 license CI failures\n- Time-to-first-response \u003c 48h; ≥5 good-first-issues open\n\n---\n\n### 🔮 Next Goals\n\n- Add retry/backoff improvements\n- OpenTelemetry instrumentation\n- Monitoring-first demo (time-series backend)\n- More error scenarios\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaurocerrato%2Fsovd-lab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaurocerrato%2Fsovd-lab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaurocerrato%2Fsovd-lab/lists"}