YAML/JSON Format for OpenSOVD CDA Diagnostic Descriptions

[bburda42dot]

Summary

OpenSOVD CDA currently consumes ECU diagnostic descriptions as .mdd runtime artifacts, typically generated from ODX/PDX.

This topic proposes adopting an official, versioned, schema-validated authoring format for diagnostic descriptions (authored as YAML or JSON, validated by a published JSON Schema) and providing a supported converter that compiles the document into a .mdd artifact that CDA already loads.

This is an additive workflow:

• ODX/PDX remains the recommended production path.
• YAML/JSON becomes a first-class option for prototyping, simulation/emulation, CI, and small/custom ECUs.

Motivation

ODX/PDX pipelines are well-suited for standards-aligned production workflows, but can be high-friction when teams need to:

• stand up a simulator/emulator quickly
• define a small custom ECU for demos or integration tests
• regenerate diagnostic descriptions in CI without heavy tooling
• avoid environments where ODX tooling complexity or licensing is a blocker

Authoring .mdd directly is not practical: it is a compact runtime artifact, not a source format.

For an open source community, a low-barrier, text-based source format also improves:

• reviewability in pull requests
• discoverability and documentation
• reproducible builds in CI
• community contributions (examples, test ECUs, reference implementations)

Goals

• Define a stable, versioned schema for diagnostic descriptions used by CDA.
• Allow authoring in YAML (human-friendly) or JSON (tool-friendly).
• Provide a clear validation story (schema validation + additional semantic validation).
• Enable a deterministic compile step into .mdd so CDA runtime remains unchanged.
• Provide an extension mechanism for OEM/vendor-specific data.

Non-goals

• Replacing ODX/PDX in production processes.
• Changing CDA runtime to load YAML/JSON directly (the proposed runtime artifact remains .mdd).
• Modeling the entire ODX information model.
• Supporting arbitrary scripting/expression evaluation in conditions/access control.

Proposal

1) Official, versioned authoring format (YAML/JSON)

Adopt an OpenSOVD CDA Diagnostic Description document format with a fixed schema identifier:

schema: "opensovd.cda.diagdesc/v1"

The normative reference is the JSON Schema (draft 2020-12). Documents may be authored as YAML or JSON, but must validate against the schema.

Key design properties (based on the current draft schema):

• Strict by default (additionalProperties: false) to catch typos.
• Minimal required core, with optional sections for advanced features.
• Standards-aligned with UDS (ISO 14229), DoIP (ISO 13400), and CAN addressing (ISO 15765) where applicable.
• Extensible via x-oem free-form objects.
• Predictable references across sections (e.g., access patterns referenced by name).

2) Supported YAML/JSON → MDD converter

Provide a supported converter/CLI that:

1. Parses YAML/JSON using safe defaults.
2. Validates against the published JSON Schema.
3. Performs additional semantic validation (cross-reference checks, contradictions, limits).
4. Compiles into the same diagnostic description payload CDA expects.
5. Packages into a .mdd artifact.

Example CLI (name TBD):

yaml-to-mdd input.yml --output ecu.mdd

CDA runtime behavior remains unchanged: CDA continues to load .mdd files as it does today.

Scope: v1 “must be useful” set

The initial schema should cover the most common constructs needed in practice:

• ECU identity and addressing/transport (DoIP first, CAN addressing as needed)
• sessions
• security access (UDS 0x27)
• authentication roles (UDS 0x29)
• reusable access patterns/policy blocks
• service capability flags and constraints
• DIDs (read/write/IO control), routines, and DTC configuration
• deterministic and safe constraint/condition model (no arbitrary evaluation)
• x-oem extensions

Developer Experience

• Schema-first: publish and version the JSON Schema with the format.
• Actionable errors: errors should report path + reason (good for PR review/CI).
• Deterministic output: same input yields identical .mdd bytes (or at least identical semantic payload) to support reproducible builds.
• Editor support: JSON Schema enables autocomplete and validation in common editors.

Compatibility and rollout

• No breaking changes: existing .mdd workflows continue unchanged.

Suggested rollout:

1. Ship YAML/JSON authoring format + validator as experimental.
2. Add YAML/JSON → MDD converter, keep it experimental until test coverage is strong.
3. Promote to stable once schema + converter + test suite mature.

Versioning is anchored on the schema id. v1 is:

• opensovd.cda.diagdesc/v1

Future breaking changes would be published as v2 with a new schema id.

Alternatives considered

• ODX-only: high friction for CI, demos, and small ECUs.
• Ad-hoc YAML without a schema: easy to start, but hard to review and easy to break.
• Load YAML directly in CDA: convenient, but increases runtime surface area and complicates compatibility. Compiling to .mdd keeps runtime stable.

Example

Example YAML, JSON schema, validation script and README.md describing it, can be found here:
https://github.com/bburda42dot/diagnostic_yaml_proposal

[mfaferek93]

@bburda42dot I see one more major benefit of adding a YAML/JSON diagnostic configuration option: it would make open-sovd more open 🙂, since it would no longer require commercial ODX tools to prototype or experiment with CDA

[floroks]

@bburda42dot I see one more major benefit of adding a YAML/JSON diagnostic configuration option: it would make open-sovd more open 🙂, since it would no longer require commercial ODX tools to prototype or experiment with CDA

agreed, re. openness - there's quite some demand by the ASAM members to open up the ODX standard more to be usable by open-source projects, and there'll be discussions in the near'ish future. my hope would be, that some open-source ODX tooling might emerge in the future.

[lh-sag]

@bburda42dot Thanks for the proposal. I haven't read through it yet, but I wanted to point you to https://github.com/rnd-ash/OpenVehicleDiag/blob/main/SCHEMA.md — another attempt at ODX-less diagnostics, though incomplete. This is just for documentation purposes; I'm not suggesting we use it.

I would welcome such contribution.

[floroks]

Some potential issues based on CDA behavior/requirements for different endpoints, might've missed things, please correct if so:

• for doip it should also be possible to define an optional gateway_address for ECUs behind a DoIP gateway

• timing parameters would vary between doip and can links on an ecu, maybe the timing configuration should be part of doip/can, instead of being independent

• there are additional communication parameters used in the CDA (e.g. doip connection delays, retries, etc.), minor: also naming of them (e.g. when used in doip, the p2 parameters would be p6). there are defaults, but you might want to be able to influence them in the diagnostic description

• state transitions (e.g. transitions between session states and security access states) - first the definition, and secondly what a service call does (e.g. hard reset will always transition back to default session and security level 0). this is required for security, and to limit what services can be called (you could allow any call in any state and rely on the ecu to limit it, but then the access configuration in the yaml would be kind of pointless).

• variant detection seems to be missing (which is manageable, but it means that you can't differentiate between boot and application modes, and what's callable in them) and different software variants, meaning you'll need to make sure you update the mdd with a new software version after flashing, and then that won't be able to handle the old variant. could also be problematic if you want to use it on a "unknown" vehicle in an offboard scenario

• while not necessarily required, we found that SDGs/SD (e.g. a way to add key/values to ecus/variants/services) can be extremely helpful in practice to differentiate between different behaviours in sovd clients. e.g. ECU with specification X has a weird issue, where you need to do Y

• some of the properties don't seem to be relevant for the CDA use-case e.g. in security access, algorithm, max_attempts and delay_on_fail_ms are defined - since the CDA doesn't calculate the key, maybe providing them as SDs to a client would make more sense?

I didn't get how the access patterns are applied to the services? Usually you'd want the ability to set them to any service. Same for the different levels in the security access. E.g. how can I say the the programming session requires a specific access pattern, and SID 34 requires security access level 5?

The CDA utilizes functional classes to distinguish between coding services (/configuration) and data services, is there a way to set that?

[bburda42dot]

Thanks for the detailed review! These are all valid points, and a few of them were indeed missing or without necessary details in my original proposal.

Over the last week I focused on improving the schema and building yaml-to-mdd converter. In result I expanded the schema and examples to cover the full end-to-end flow:
YAML -> MDD -> CDA

Full workflow and updated schema are in:

• PR: YAML schema, yaml-to-mdd converter, and CDA integration bburda42dot/diagnostic_yaml_proposal#1
• Branch: https://github.com/bburda42dot/diagnostic_yaml_proposal/tree/feat/yaml-to-mdd

I’m still validating 100% of the generated MDD files against CDA expectations with real HW plugged in, but you can already run the minimal example end-to-end and see that CDA starts and works with the generated output.

One small clarification on intent: the goal is not to replace ODX with YAML. ODX/PDX remains the standard and the long-term production source of truth. The YAML/JSON format is meant as an easy on-ramp / pragmatic authoring format for quickly bringing up and iterating on a diagnostic stack (prototypes, simulators/emulators, minimal ECUs, CI use-cases, etc.). If the community agrees this direction makes sense, I’m happy to incrementally add missing features as we converge on what CDA needs in practice.

Addressing your specific points:

1. DoIP gateway / gateway_address
   Good catch. The current schema models direct DoIP endpoints (ecu.addressing.doip: ip/port + logical/tester addressing). I agree we should add an optional gateway_address (or a dedicated “via gateway” node) for ECUs behind a DoIP gateway. I can add this and map it cleanly into MDD/CDA.

2. Timing parameters differ between DoIP vs CAN
   Today base UDS timing is modelled under ecu.addressing.timing (P2/P2*/S3) with optional per-session overrides (sessions.*.timing). Protocol/link-specific knobs (connect timeouts, retries, delays, etc.) are carried via comparams.{doip,can,...}. I agree the base timing likely should be protocol-scoped (or at least have clear precedence rules), and I can align this with how CDA expects to resolve timing per link.

3. Additional CDA communication parameters (delays, retries, naming like P2 vs P6, etc.)
   This was one of the gaps I addressed: the updated schema introduces comparams with global defaults and per-protocol overrides (doip, can, uds, iso15765) plus optional typed specs (type/unit/default/constraints). This is intended exactly for these transport/protocol parameters. On naming (P2 vs P6 etc.): the schema is spec-driven (not hardcoded), so we can standardize naming/mapping in the converter as we align with CDA expectations.

4. State transitions / stateful gating
   Added state_model (initial state, allowed session transitions, reset-on-session-change toggles, S3 timeout behavior) and service-level state_effects where deterministic transitions are needed (diagnosticSessionControl, ecuReset, securityAccess, authentication). The example already models hard reset -> default session / security none, etc.

5. Variant detection + SW variants / unknown vehicle
   This is now explicitly covered via variants (ordered detection via detection_order, configurable fallback, plus per-variant overrides of services/DIDs/routines/access_patterns/state_model). The example includes bootloader vs application detection and an unknown fallback “safe mode”.

6. SDGs/SD and client hints
   Included both hierarchical sdgs (ODX-like SDG/SD concept) and lightweight annotations for pragmatic key/value hints to differentiate client behavior.

7. How access patterns are applied (e.g. session/security constraints, SID 0x34 requires level 5)
   Access patterns are defined in access_patterns and referenced by actual call targets: dids.*.access, routines.*.access, memory regions for 0x23/0x3D/0x34/0x35 (services.*.regions[].access), and services.custom.*.access. This covers cases like “SID 0x34 requires security level 5” via region-level gating.
   For “enter programming session requires X”: currently session entry is expressed via sessions.*.requires_unlock plus allowed_sessions in security/auth role definitions. Access patterns are not attachable directly to DSC subfunctions yet. If CDA needs explicit access gating on session entry (or on standard services), we can extend the schema accordingly.