2.2. SOVD (ISO 17978-1)¶
The guiding principle behind this document is to specify the requirements for an ISO 17978-1 compatible API in the Eclipse OpenSOVD Classic Diagnostic Adapter (CDA).
2.2.1. General¶
Paths and parameter names should be case-insensitive, unless otherwise mentioned.
2.2.2. HTTP(S)¶
The CDA must provide an HTTP- or HTTPS-server. The HTTP Server has to support multiple connections, and calls should be handled asynchronously. Rationale Multiple clients might use the CDA at the same time, and asynchronous handling generally improves performance due to reduced thread count. |
The HTTP- or HTTPS-Server port must be configurable. |
In case of HTTPS, the certificate/key must be providable through the configuration, or a plugin. Rationale Certificates/Keys might be stored in an HSM, therefore platform specific code might be needed for access. |
2.2.3. API¶
2.2.3.1. Entities¶
Data types must be mapped as specified by ISO 17978-3. Additionally, for the data type |
2.2.3.2. Paths¶
The CDA must provide a Each ECU with a loaded diagnostic description (MDD file) must be represented as an entity in the collection.
Rationale The |
Software Requirement: Standardized Resource Collection Mapping req~sovd-api-standardized-resource-collection-mapping
|
||||||||||||||||||||||||||||||||||||
The standardized resource collection for
NOTE: The mapping in ISO standard is inconsistent w.r.t. Query Parameters The CDA must support the optional query parameter |
The CDA must return the Special Data Groups (SDGs) and Special Data (SDs) from the diagnostic description when the
optional query parameter This query parameter must be supported on:
The
When no SDGs are available for the requested resource, the Rationale SDGs carry vendor-specific metadata from the diagnostic description (e.g. bus interface type, AUTOSAR version) that clients may need for display or decision-making purposes. Making them opt-in through a query parameter avoids unnecessary overhead in the default response. |
The CDA must support ECU variant detection through a Rationale Some ECUs have different variants, which support different functionality. To provide the correct functionality, the CDA needs to be able to detect the variant in use. This variant may change at any point due to the nature of the ECUs software. Clients may need to trigger this explicitly to ensure correct functionality. |
2.2.3.2.1. Operations¶
Operations (Routines SID 3116) can be synchronous or asynchronous. Asynchronous routines are routines, for which the The order of operations:
Synchronous routines The POST to executions will directly return the result - either a 200 with the data, or an error. Example of a successful call: {
"parameters": {
"key": "value"
}
}
Asynchronous routines Since the response of the Example of a successful call: {
"id": "<id of created execution>",
"status": "running",
"parameters": {
"key": "value"
}
}
Should the call to the There are however use-cases, in which you may want to call |
2.2.3.2.2. Faults¶
The CDA must provide a |
2.2.4. Extensions to the ISO specification¶
2.2.4.1. Data Type A_BYTEFIELD as Hex¶
For the data type Rationale Handling base64 encoded binary directly can be a compatibility challenge for offboard testers accessing the CDA. Manual debugging can also be simplified by directly seeing the hexadecimal encoded data, since it’s easier to process for humans. |
2.2.4.2. Support for mimetype application/octet-stream¶
Software Requirement: Support for mimetype application/octet-stream req~sovd-api-octet-stream-support
|
The NOTE: Only the payload is sent/received. The SID & DID/RID are derived from the path, and in case of NRCs only the NRC code (single byte) is sent back with a HTTP 502. Rationale This requirement simplifies the use of the CDA as a diagnostic tester and in migration scenarios. |
2.2.4.3. Version Info Endpoint¶
The CDA must provide a The endpoint shall return a JSON response containing
The
The path to the Rationale Allows SOVD clients to discover which API versions are supported by the server before attempting to access version-specific resources. |
The CDA may optionally provide vendor-specific version data endpoints at These endpoints are registered by the same registration function that provides the standard
Rationale Provides a convenient vendor-specific endpoint for tooling that expects implementation details in a structured data format without needing to parse the standard version-info response. |
A single registration function shall accept the following parameters:
The function shall always register the The function shall optionally register the Rationale Centralizes version endpoint registration into a single callable unit, ensuring consistency between the standard version-info response and optional vendor-specific endpoints. |
2.2.4.4. Health Endpoint¶
The CDA MAY provide a health monitoring endpoint as an optional build-time feature. When the health monitoring feature is enabled:
When the health monitoring feature is disabled:
Rationale Health monitoring enables external systems (e.g., container orchestrators, load balancers, or monitoring systems) to observe CDA startup progress and operational status. Making this an optional build-time feature allows deployments that do not require health monitoring to reduce the application footprint and avoid unnecessary overhead. |
2.2.4.5. Support for non-standard operation order¶
Software Requirement: Support for non-standard operation order req~sovd-api-routine-operation-out-of-order
|
|||||||||
To support the use-case of calling
When a REST call is initiated that needs to call the service on the ECU, but is missing the required
definition in the diagnostic description, and |
2.2.4.6. Vehicle¶
A vehicle must support operations as a whole, to allow for operations which affect the whole vehicle, like updating mdd-files, or to prepare for operations which affect the whole vehicle (e.g. disabling vehicle communication).
Vehicle level operations must be supported in the CDA.
This requires a standardized resource collection in the exposed root path The standardized resource collection must provide the following resources:
|
2.2.4.7. Locks¶
Locks allow clients to claim exclusive or non-exclusive access to a diagnostic entity (vehicle, ECU, or functional group) and to coordinate diagnostic communication across multiple concurrent clients. The same CRUD API and enforcement semantics apply to all three lock scopes.
All three lock scopes – vehicle (
The request body for POST and PUT must support the following fields:
The POST response must include Keys and Values must be case-insensitive. Rationale A unified lock API across all three scopes reduces client implementation complexity and ensures consistent lock management regardless of the diagnostic entity type. |
A lock must be either exclusive or non-exclusive, controlled by the Exclusive lock ( While an exclusive lock is held, all requests to the locked entity’s ECU-communication endpoints from clients that do not own the lock must be rejected with HTTP 423. Non-exclusive lock ( While a non-exclusive lock is held:
Rationale Non-exclusive locks allow monitoring or logging clients to continue reading diagnostic data while a primary client holds the entity for active diagnostic communication. |
The CDA must support a global configuration option, The following values must be supported:
This option applies globally across all three lock scopes (vehicle, ECU, and
functional group). Requests that explicitly set Rationale Defaulting to exclusive locks favors a safe-by-default posture, preventing accidental
concurrent access to a diagnostic entity when a client omits the exclusivity field.
Deployments that prefer the non-exclusive default, for example to support monitoring-friendly
workflows without requiring every client to set the field explicitly, may set this option to
|
Every lock must carry a positive expiration duration in seconds (
Rationale Automatic expiration prevents abandoned locks from clients that disconnect unexpectedly from blocking other clients indefinitely. |
When an ECU lock is held, the following rules must apply to requests targeting that ECU’s communication endpoints. The caller’s identity is determined from the JWT claims.
Write endpoints: Read endpoints: Error Messages Errors shall follow the standard SOVD error pattern. In case a lock was preempted,
the error code When a resource is accessed, which requires a lock, or is currently locked by a different
client, the error code Rationale Requiring a lock for write operations prevents concurrent modification of ECU state. Allowing reads without a lock when no exclusive lock is held supports monitoring clients that do not need to coordinate with active diagnostic sessions. Exclusive locks are required on critical ECU operations like flashing, when a stray read operation can cause failures. |
The same enforcement rules defined in ECU Lock Endpoint Enforcement (req~sovd-api-lock-ecu-enforcement) apply
to requests targeting a functional group’s communication endpoints:
|
The CDA must support a configurable option, The following values must be supported:
This option applies uniformly to both ECU-scoped and functional-group-scoped communication endpoints. Rationale Some deployments require every diagnostic interaction with an ECU or functional group – including read-only monitoring requests – to be attributable to an active, identifiable lock owner, for example to satisfy audit or safety-case requirements. Other deployments want unlocked reads to remain possible for monitoring or logging clients. Modeling the option as an enumeration keeps the configuration surface future-proof for additional requirement policies without introducing further boolean flags. |
The CDA must support a configurable option, The following values must be supported:
This requirement is independent of, and must not be confused with,
Vehicle Lock Blocks Child L... (req~sovd-api-lock-vehicle-blocking): that requirement governs what happens to
other clients while a vehicle lock is held (blocking their acquisition of child
locks), whereas Rationale Some deployments require all ECU- and functional-group-level diagnostic locking to occur strictly within the scope of an overarching vehicle-level claim, ensuring no diagnostic entity can be locked in isolation without an active vehicle-wide session already having been established. Modeling the option as an enumeration keeps the configuration surface future-proof for additional acquisition policies (e.g. hierarchical or vendor-specific schemes) without introducing further boolean flags. |
When a vehicle lock is held by a client, any other clients attempt to acquire an ECU lock or a functional group lock must be rejected with HTTP 409. The vehicle lock owner may still acquire ECU or functional group locks. Rationale The vehicle lock represents a claim over the complete set of diagnostic entities on the vehicle. Permitting other clients to acquire child locks while the vehicle lock is held would violate that claim. |
The CDA must support a vendor-configurable lock preemption mechanism applicable to vehicle locks. A lock POST request may include additional fields in the request body, these can be used by a vendor specific implementation to allow lock overrides. Note, the vendor specific implementation must be aware of the current lock holders additional fields, since they can impact the priority decision. The mechanism retrieves: - the requesting client’s JWT claims, - the additional values from the request body, and - the identity of the current lock holder and additional metadata. The mechanism returns:
If the mechanism grants preemption, the existing lock transitions to a defunct state (see Defunct Lock State (req~sovd-api-lock-defunct)) and the requesting client immediately acquires the lock. If no vendor mechanism is configured, or if the mechanism does not grant preemption, conflicting POST requests are rejected with HTTP 423 as normal. Rationale In multi-client environments certain clients (e.g. OEM tooling, safety-critical services) require guaranteed access to diagnostic entities for specific use-cases, even when another client holds the lock. Delegating the preemption decision to a vendor mechanism allows vendors to implement any priority scheme without modifying the CDA core. |
When a lock is preempted by a higher-priority client it must transition to a defunct state. The following rules apply:
Rationale Retaining the defunct lock gives the preempted client an observable signal that their lock was superseded, identifying who took it and when, and if a lock is still held. |
When a client whose lock has been made defunct attempts to call any ECU communication endpoint, the CDA must return HTTP 409 (Conflict). HTTP 409 applies to all communication endpoints (e.g. data, configurations, operations,
modes, faults, genericservice, x-sovd2uds-download). It does not apply to the Rationale HTTP 409 distinguishes preemption from other failures, giving the preempted client an actionable signal that a higher-priority client has taken over the diagnostic entity. This is also the reason for the error being applied to all read communications, even if the higher prioritized lock is non-exclusive. |
2.2.4.8. Functional communication¶
Functional communications needs to be possible. A standardized resource collection must be made available within the
The available functionality must be defined in an additional diagnostic description used solely for defining functional communication services. Since this file may contain multiple logical link definitions, a configuration option can be provided to filter the available links. The following entities must be available in the functional groups resource collection:
Rationale Clients require functional communication to ECUs for use-cases, in which they want to control communication or dtcsettings for all ecus. |
2.2.4.9. Flash API¶
A Flash-API is required to support flashing of ECUs, utilizing SIDs 3416, 3616 & 3716. It needs to enable efficient transfer of the data, without sending the individual data transfers via REST. Flashing is the process of updating the firmware of an ECU. Rationale Handling for the aforementioned SIDs isn’t defined in the ISO specification, it is however an important use-case to be able to update the firmware on ECUs. |
The source of the data to be sent for flashing, must be restrictable to a path and its subdirectories via configuration. Rationale Without restrictions to the path, an attacker could exfiltrate arbitrary accessible data. |
2.2.4.10. Communication Parameters API¶
An API to retrieve and modify communication parameters must be provided Rationale Clients need the ability to modify communication parameters on-the-fly to communicate with classic ECUs. |
2.2.4.11. MDD Embedded files¶
The CDA must support reading embedded files from the MDD file, and provide them via the
Rationale Some data required for communication with ECUs might be embedded in the mdd file. To allow clients to retrieve this data, it must be made available through the API. |
2.2.4.12. Security¶
Since vendors have different requirements and systems regarding security, security related functionality has to be implemented in a plugin, see Security.
2.2.4.12.1. Token validation¶
2.2.4.12.2. Audiences¶
2.2.4.12.3. Session States¶
2.2.5. OpenAPI-Documentation¶
An OpenAPI documentation of the provided API must be available for every endpoint of the CDA when Rationale Required by the standard. |
An OpenAPI schema description of the retrieved data must be included in the response when the query
parameter Rationale Required by the standard. |