3.3.3. SOVD-API¶
3.3.3.1. Data Types¶
Data types must be mapped as follows:
Primitive JSON types All primitive JSON types (string, array, number, integer, boolean, and object) can be used. For strings, the following format identifiers can be used:
Note TODO More string formats required? Mapping of complex data types Note TODO Mapping of complex data types |
3.3.3.2. Bulk Data¶
Bulk-data endpoints allow the management of bulk data, like files that are to be used for flashing. Paths are required to be in the following structure:
Note IMPORTANT: All calls to the aforementioned endpoints can fail with reasonable HTTP status codes (e.g. 401, 403, 409, 501), depending on the context and state.
|
![' SPDX-FileCopyrightText: 2026 Copyright (c) Contributors to the Eclipse Foundation
'
' See the NOTICE file(s) distributed with this work for additional
' information regarding copyright ownership.
'
' This program and the accompanying materials are made available under the
' terms of the Apache License Version 2.0 which is available at
' https://www.apache.org/licenses/LICENSE-2.0
'
' SPDX-License-Identifier: Apache-2.0
@startuml
title Bulk-Data Endpoints
participant Client
participant "HTTP Server\n(Axum)" as HTTP
participant "Security\nMiddleware" as SEC
participant "Bulk-Data\nHandler" as HANDLER
participant "File System /\nStorage" as FS
== List entries ==
Client -> HTTP : GET /bulk-data/{category}
activate HTTP
HTTP -> SEC : authenticate & authorize
activate SEC
SEC -> HTTP : OK
deactivate SEC
HTTP -> HANDLER : route to bulk-data handler
activate HANDLER
HANDLER -> FS : list entries in category
activate FS
FS -> HANDLER : entries with IDs and metadata
deactivate FS
HANDLER -> HTTP : JSON body
deactivate HANDLER
HTTP -> Client : HTTP 200 OK\n{ "items": [ { "id": "...", ... }, ... ] }
deactivate HTTP
== Download entry ==
Client -> HTTP : GET /bulk-data/{category}/{entry-id}
activate HTTP
HTTP -> SEC : authenticate & authorize
activate SEC
SEC -> HTTP : OK
deactivate SEC
HTTP -> HANDLER : route to bulk-data handler
activate HANDLER
HANDLER -> FS : read entry data
activate FS
FS -> HANDLER : binary data
deactivate FS
HANDLER -> HTTP : binary response\n(MIME type determined by content)
deactivate HANDLER
HTTP -> Client : HTTP 200 OK\nContent-Type: <mime-type>\n<binary data>
deactivate HTTP
== Upload entry ==
Client -> HTTP : POST /bulk-data/{category}\nContent-Disposition: form-data\n<binary data>
activate HTTP
HTTP -> SEC : authenticate & authorize
activate SEC
SEC -> HTTP : OK
deactivate SEC
HTTP -> HANDLER : route to bulk-data handler
activate HANDLER
HANDLER -> FS : store data with metadata
activate FS
FS -> HANDLER : stored (entry-id)
deactivate FS
HANDLER -> HTTP : JSON body
deactivate HANDLER
HTTP -> Client : HTTP 201 Created\n{ "id": "<entry-id>" }
deactivate HTTP
== Delete entry ==
Client -> HTTP : DELETE /bulk-data/{category}/{entry-id}
activate HTTP
HTTP -> SEC : authenticate & authorize
activate SEC
SEC -> HTTP : OK
deactivate SEC
HTTP -> HANDLER : route to bulk-data handler
activate HANDLER
HANDLER -> FS : delete entry
activate FS
FS -> HANDLER : deleted
deactivate FS
HANDLER -> HTTP : success
deactivate HANDLER
HTTP -> Client : HTTP 204 No Content
deactivate HTTP
@enduml](../../_images/plantuml-2f5a5ec5ff5b44e8ad403b02dedfb1ae35c273d8.png)
3.3.3.3. Entities¶
The GET /components Returns a list of all ECU entities that have been loaded from diagnostic descriptions (MDD files). Each item in the list contains the ECU name, a lowercase identifier, and a URI reference to the individual component resource. The response may include additional fields beyond the standard GET /components/{ecu-name} Returns detailed information about a specific ECU entity, including:
The connectivity state of an ECU reflects its current diagnostic reachability and variant detection status:
Optionally, diagnostic description metadata (SDGs) for the ECU can be included in the response through a query parameter. |
Software Architecture: Standardized Resource Collection Mapping arch~sovd-api-standardized-resource-collection-mapping
|
Every ECU with a This doesn’t include the |
3.3.3.4. ECU resource collection¶
Each ECU entity must provide a standardized resource collection as defined in ISO 17978-3, chapter 5.4.2. The resource collection for ECUs is defined in an OpenAPI Specification: |
3.3.3.5. SDG/SD Metadata¶
Special Data Groups (SDGs) and Special Data (SDs) from the diagnostic description can be retrieved through an
opt-in query parameter ECU-level SDGs On the Service-level SDGs On the Operation-level SDGs On the For asynchronous operations (which consist of multiple subfunctions such as Start, Stop, RequestResults),
each subfunction’s SDGs are returned as separate entries in the Data format The SDG/SD structure is recursive. Each entry in the list is one of two types:
SD and SDG entries are distinguished by their structure – an entry with a |
3.3.3.6. Data Resources – SID 2216 & 2E16¶
Data resources for ECUs are available in the standardized resource collection within the path The data main path returns a list of the data identifiers available as A data identifier in the list is described with the following attributes (all strings):
Naming Names for data resources are determined by taking all diag-services defined for 2216 and 2E16 – their short name is taken as a base and processed by removing configurable prefixes/suffixes, to determine the data identifier within the The following diagrams illustrate the message flow for reading and writing data resources:
|
3.3.3.7. Categories¶
The category of a data identifier must be mappable with configuration, in which the functional class name is mapped to a category name. The following standard categories are defined by the standard:
Additional custom categories must be prefixed with Services without a mapping should be ignored to allow a separation between configuration and data services. |
3.3.3.8. Configurations – SID 2216 & 2E16¶
Names for data resources are determined by taking all diag-services defined for 2216 and 2E16, and filtering
them for a configurable functional class name. Their short name is taken as a base and processed by removing
configurable prefixes/suffixes, to determine the data identifier within the The returned item properties for the
The following diagrams illustrate the message flow for reading and writing configuration resources:
Note
Rationale for serviceAbstract Coding data files might not include the matching name for a service, or detailed JSON parameters that would
be required to code an ECU. Therefore, a “reverse lookup” to the name can be required, so a client without
access to the diagnostic description is able to code an ECU just with the |
3.3.4. Operations¶
Operations in the CDA are Routines (3116), Reset (1116), and an extension to configure communication parameters (Communication Parameters (ComParams)). Reset – SID 1116 For compatibility with SOVD version 1.0 and earlier, the operations Routines – SID 3116 All services with the SID 3116 are considered for operations – as with data, their short names are
preprocessed by removing configurable prefixes/suffixes to determine routine identifiers available as
the The items in the list of items available under
Synchronous – Start only When a routine only defines the
Note Operations without a Asynchronous – Stop and/or RequestResults When a routine has The POST request returns HTTP status Additionally, by calling Subfunction Requirements If any of the required subfunctions are not available in the diagnostic database, the call will result in an error:
These requirements can be bypassed using the Force Parameter If DELETE is called and an ECU error is encountered, the When
Stop Response Data When a Stop subfunction returns non-empty response data, the DELETE endpoint returns HTTP status
Note This is an extension to the standard to support Stop operations that return response data. Rationale for POST Response Data When executing an asynchronous function, there’s no good way to return the response of the routine with the GET to the id-endpoint, since that endpoint should only return the status of the RequestResults call. Therefore, the response of the routine is returned directly when executing the routine with POST in addition to the id. Note This is a deviation from the standard, but is required to allow clients to handle routine responses properly. |
3.3.4.1. IOControl – SID 2A16¶
Note
Not supported at this time
3.3.5. Modes¶
3.3.5.1. Session – SID 1016¶
The endpoint
The format for the request body is: {
"value": "<session name>",
"mode_expiration": 3600
}
The names of the sessions for the field The field In the response body, See also chapter 7.16 in ISO 17978-3.
|
3.3.5.2. Security – SID 2716¶
The endpoints are available under the path Works similarly to Session defined in the previous chapter. The names of the security access levels are determined through the state charts for the SID 2716 services. RequestSeed flow A client initiates security access by sending a
Example values and their parsed components:
RequestSeed service name resolution The CDA resolves the UDS RequestSeed service (SID 2716) by searching all SID 2716 services in the ISO 14229-1 RequestSeed subfunction range (odd subfunctions 1, 3-5, 7-41, exactly 2 request parameters) and selecting the first whose short name contains the level name (underscores stripped, case-insensitive). This requires the level name to be embedded in the service short name, which both supported naming conventions satisfy:
|
3.3.5.3. Authentication – SID 2916¶
Note This is technically a deviation from Table 343 in the ISO API. The table in the ISO is misleading, since 8.3.2 and 8.3.3 describe them separately. The endpoints are available under Diagnostic data descriptions have to specify the used services including the subfunction individually, so the request parameters can be converted into UDS payloads.
|
3.3.5.4. Communication Control – SID 2816¶
To control the communication parameters of an ECU, the path The attribute
Matching 2816 service entries must be present in the diagnostic description. Parameters can be provided
through an additional Note Other values are not supported.
|
3.3.5.5. DTC Setting – SID 8516¶
To control the DTC settings of an ECU, the path The attribute Matching 8516 service entries must be present in the diagnostic description. Parameters can be provided
through an additional Note Other specific extensions to the values are not supported.
|
3.3.6. Faults – SID 1416 & 1916¶
The following operations must be implemented:
The query parameter Available keys:
All values are either boolean values (true/false), or a bit value (0/1). Additionally, a special key called
|
![' SPDX-FileCopyrightText: 2026 Copyright (c) Contributors to the Eclipse Foundation
'
' See the NOTICE file(s) distributed with this work for additional
' information regarding copyright ownership.
'
' This program and the accompanying materials are made available under the
' terms of the Apache License Version 2.0 which is available at
' https://www.apache.org/licenses/LICENSE-2.0
'
' SPDX-License-Identifier: Apache-2.0
@startuml
title Fault Read -- SID 19
participant Client
participant CDA
participant "Diagnostic\nKernel" as DIAG
participant "UDS / DoIP" as COMM
participant ECU
== List All Faults ==
Client -> CDA : GET /components/{ecu}/faults\n?status[confirmedDtc]=true
activate CDA
CDA -> DIAG : read DTCs (status mask)
activate DIAG
DIAG -> DIAG : build status mask byte\nfrom query parameters
DIAG -> COMM : send UDS request
activate COMM
COMM -> ECU : DoIP -> UDS ReadDTCInformation\n(19 02 {status mask})
activate ECU
ECU -> COMM : positive response\n(59 02 {availability mask} {DTC records})
deactivate ECU
COMM -> DIAG : raw UDS response
deactivate COMM
DIAG -> DIAG : parse DTC records\n(DTC number + status byte)
DIAG -> CDA : list of DTCs with status
deactivate DIAG
CDA -> CDA : map DTCs to SOVD\nfault representation
CDA -> Client : HTTP 200 OK\n{ "items": [ { "id": "...", "status": { ... } }, ... ] }
deactivate CDA
== Read Single Fault with Extended Data ==
Client -> CDA : GET /components/{ecu}/faults/{dtc}\n?include-extended-data=true&include-snapshot=true
activate CDA
CDA -> DIAG : read DTC detail + extended + snapshot
activate DIAG
DIAG -> COMM : send UDS request(s)
activate COMM
COMM -> ECU : ReadDTCInformation\n(19 04/06 {DTC} ...)
activate ECU
ECU -> COMM : positive response(s)\nwith snapshot & extended data
deactivate ECU
COMM -> DIAG : raw UDS response(s)
deactivate COMM
DIAG -> DIAG : decode snapshot &\nextended data records
DIAG -> CDA : DTC detail with environment data
deactivate DIAG
CDA -> Client : HTTP 200 OK\n{ "id": "...", "status": { ... },\n "environment_data": { ... } }
deactivate CDA
@enduml](../../_images/plantuml-96d32b7774fab847742cdb402b17b3bab1898b1e.png)
3.3.7. Locks¶
All three lock scopes share the same CRUD API shape. The scope paths are:
Request fields (POST / PUT)
Response fields (POST / PUT)
Response fields (GET /locks/{id})
|
The |
The configured
The substitution is performed identically for the vehicle, ECU, and functional group lock handlers. Being enum-typed, this configuration option is designed to accommodate additional exclusivity policies in the future without changing its name or structure. Requests that explicitly include |
When a lock is created, a background task is spawned that fires at the computed absolute expiration instant. On firing, the task acquires the write lock on the lock map, confirms the stored lock ID still matches (guarding against a race with an extend or a preemption), invokes the lock’s cleanup function, and removes it from the map. On On explicit Defunct locks retain their original expiration task, but the task only removes the defunct entry from the defunct store without invoking cleanup. |
A
ECU Lock Enforcement Decision¶ The check accepts a vehicle lock owned by the caller as equivalent to owning the ECU lock, granting full write access. |
A See also Functional Communication EC... (arch~sovd-api-functional-communication-locks) for the Tester Present side-effects associated with acquiring and releasing a functional group lock. |
The configured
All other branches of the decision logic – defunct lock pre-check, exclusive/ non-exclusive handling while a lock is held by another client, and the vehicle-lock equivalence check – are unaffected by this option. Being enum-typed, this configuration option is designed to accommodate additional requirement policies in the future without changing its name or structure. |
The ECU lock POST handler and the functional group lock POST handler each evaluate the
configured
Being enum-typed, this configuration option is designed to accommodate additional acquisition policies in the future without changing its name or structure. |
Software Architecture: Vehicle Lock Blocks Child Lock Acquisition arch~sovd-api-lock-vehicle-blocking
|
The ECU lock POST handler and the functional group lock POST handler each check for an active vehicle lock before creating the child lock. If a vehicle lock is present and owned by a different client the request is rejected with HTTP 409. If the vehicle lock is held by the same caller, or if no vehicle lock is held, the child lock creation proceeds normally. |
When a lock POST request arrives and a lock is already held by a different client, the priority mechanism – if one is registered – is invoked before returning HTTP 409. Mechanism input
Mechanism output
If |
When preemption is granted by the priority mechanism:
|
The
This pre-check takes precedence over the HTTP 409 or HTTP 423 that would otherwise be returned for a missing or non-owned active lock. |
3.3.8. Generic Service¶
The The client sends a hex-encoded UDS request in the JSON body, and receives the raw hex-encoded UDS response from the ECU. Permissions for generic service calls can be checked and enforced through the security plugin. Since
generic service requests bypass the structured service resolution, the security plugin receives the
raw UDS request payload (e.g.
|
3.3.9. Version Endpoint¶
Software Architecture: API Version Endpoint Registration Function arch~sovd-api-version-registration-function
|
The CDA provides a version registration function that sets up version-related endpoints during initialization. Registration Function The function accepts the following parameters: It always registers the standard The fields Standard Endpoint: /version-info The {
"sovd_info": [
{
"version": "<sovd_api_version>",
"base_uri": "<relative uri-reference to base of sovd_api_version>",
"vendor_info": {
"name": "<vendor_name>",
"version": "<implementation_version>",
"commit": "<commit>",
"build_date": "<build_date>"
}
}
]
}
Optional Vendor-Specific Endpoints: /data/version, /apps/sovd2uds/data/version When enabled, these endpoints are registered as static data endpoints returning: {
"id": "version",
"data": {
"name": "<vendor_name>",
"api": {
"version": "<api_version>"
},
"implementation": {
"version": "<implementation_version>",
"commit": "<commit>",
"build_date": "<build_date>"
}
}
}
Both endpoint types are available immediately after the HTTP server starts and do not require any ECU communication.
Note The current implementation only registers |
![' SPDX-FileCopyrightText: 2026 Copyright (c) Contributors to the Eclipse Foundation
'
' See the NOTICE file(s) distributed with this work for additional
' information regarding copyright ownership.
'
' This program and the accompanying materials are made available under the
' terms of the Apache License Version 2.0 which is available at
' https://www.apache.org/licenses/LICENSE-2.0
'
' SPDX-License-Identifier: Apache-2.0
@startuml
title Version Registration Function
participant "Application\nStartup" as APP
participant "Version\nRegistration\nFunction" as VREG
participant "HTTP Server\n(Axum)" as HTTP
APP -> VREG : register_version_endpoints(\nvendor_name, implementation_version,\ncommit, build_date)
activate VREG
VREG -> VREG : determine base_uri\nand api_version
VREG -> HTTP : register GET /version-info
activate HTTP
HTTP -> VREG : registered
deactivate HTTP
alt optional vendor-specific endpoints enabled
VREG -> HTTP : register GET /data/version
activate HTTP
HTTP -> VREG : registered
deactivate HTTP
VREG -> HTTP : register GET /apps/sovd2uds/data/version
activate HTTP
HTTP -> VREG : registered
deactivate HTTP
end
VREG -> APP : registration complete
deactivate VREG
== Runtime: Client requests version info ==
participant Client
Client -> HTTP : GET /version-info
activate HTTP
HTTP -> Client : HTTP 200 OK\n{ "sovd_info": [ { "version": "...",\n"base_uri": "...", "vendor_info": { ... } } ] }
deactivate HTTP
@enduml](../../_images/plantuml-7feeadac5180585ff4e111c2da668589046a154d.png)
3.3.10. Error Codes & Messages¶
Note
todo define