`JSON-cppagent-mqtt`: `Header.schemaVersion` absent on MQTT Streams Header

[ottobolyos]

Summary

Under the JSON-CPPAGENT-MQTT document format, the MTConnectStreams.Header object does not include a schemaVersion property, even though cppagent's JSON v2 printer emits schemaVersion inside the Header (in addition to at the top level). Consumers reading MTConnectStreams.Header.schemaVersion directly — as the cppagent reference output permits — get undefined from MT.NET payloads.

Environment

• MTConnect.NET-Applications-Agents + MTConnect.NET-JSON-cppagent at v6.9.0 (official Docker image trakhound/mtconnect.net-agent:6.9.0, published 2025-10-16 — binary-equivalent to the v6.9.0.2 release as of 2026-04-20).
• Broker: eclipse-mosquitto:2.0.22.
• Comparison agent: mtconnect/agent:latest = cppagent v2.7.0.7 (2026-04-09) with JsonVersion = 2, SchemaVersion = 2.7.
• Format ID: JSON-CPPAGENT-MQTT.

Reproduction

Minimum rig (mqtt-relay module with documentFormat: JSON-CPPAGENT-MQTT pointed at a local Mosquitto; any device model will do):

# applications/MTConnect-Agent/appsettings.yaml (MT.NET side)
modules:
- mqtt-relay:
    server: localhost
    port: 1883
    documentFormat: JSON-CPPAGENT-MQTT
    topicPrefix: MTConnect/Document
    topicStructure: Document

Run the agent, subscribe to the Current topic, and inspect the Header's keys:

mosquitto_sub -h localhost -t 'MTConnect/Document/Current/<uuid>' -C 1 \
  | jq '.MTConnectStreams.Header | keys'

Observed — MT.NET Current Header keys

["instanceId", "version", "sender", "bufferSize",
 "firstSequence", "lastSequence", "nextSequence",
 "deviceModelChangeTime", "creationTime"]

No schemaVersion key. No testIndicator key (that divergence is the companion issue #131).

Expected — cppagent v2 Current Header keys

Run an identical rig on mtconnect/agent:latest (cppagent) with JsonVersion = 2, Sinks { MqttService { MqttHost = localhost } }, and subscribe to the matching MTConnect/Current/<uuid> topic:

["version", "creationTime", "testIndicator", "instanceId", "sender",
 "schemaVersion", "deviceModelChangeTime", "bufferSize",
 "nextSequence", "lastSequence", "firstSequence"]

cppagent's Header carries schemaVersion: "2.7" alongside the other agent-provenance fields. MT.NET omits it — schemaVersion lives only at MTConnectStreams.schemaVersion (top-level, sibling of Header) and is further hardcoded to "2.0" (see the companion issue #128).

Evidence files: current.json (MT.NET) + cppagent-current.json (cppagent).

Authority

JSON is not part of the MTConnect normative standard. The authority here is the cppagent JSON v2 printer's output, which JSON-CPPAGENT-MQTT is named to promise compatibility with. cppagent's test_package/json_printer_stream_test.cpp exercises the Header under v2 and the live output includes schemaVersion inside it. See also the XMI / prose standard's treatment of schemaVersion as an envelope-level MTConnect-release declaration — which cppagent surfaces in both the Header and the top-level slot for consumer convenience.

Root cause — library source

libraries/MTConnect.NET-JSON-cppagent/Streams/JsonStreamsHeader.cs does not declare a SchemaVersion property. The Header-equivalent class never carries the field; only the wrapper (JsonMTConnectStreams) does — and even there it's hardcoded (see issue #128).

Impact

• Consumers that read MTConnectStreams.Header.schemaVersion (a natural path, since Header.version exists as a sibling) get undefined from MT.NET.
• Combined with companion issue MTConnectStreams.schemaVersion / MTConnectDevices.schemaVersion hardcoded to "2.0" in JSON-cppagent-mqtt formatter #128's hardcoded "2.0" at top-level, there is no way for a consumer to learn the agent's true MTConnect release from the MT.NET JSON envelope.
• Divergence severity is Low–Medium on its own, but compounds with drafts 01 and 02 to make version-identification entirely broken.

Suggested fix

1. Add SchemaVersion as a JSON-serialised property on JsonStreamsHeader (and JsonDevicesHeader, and JsonAssetsHeader) so the Header carries the agent's MTConnect release inside it, matching cppagent's JSON v2 shape.
2. Populate from the same DefaultVersion pathway that draft 02 recommends threading through JsonMTConnectStreams. A single shared accessor is cleanest.

Stability across MTConnect versions

Unchanged — the cppagent JSON v2 convention to emit schemaVersion inside Header has been stable across cppagent's v2 JSON lineage and is not tied to any particular MTConnect release. Fixing it here is a single-location code change that works across v2.x and the forthcoming v2.6 / v2.7 uplift.

Related issues

• MTConnectStreams.schemaVersion / MTConnectDevices.schemaVersion hardcoded to "2.0" in JSON-cppagent-mqtt formatter #128 — MTConnectStreams.schemaVersion / MTConnectDevices.schemaVersion hardcoded to "2.0" — same root (no threading of DefaultVersion); fix should land in one PR.
• Header.version reports library assembly version instead of MTConnect release #127 — Header.version reports library assembly version — adjacent Header defect.
• JSON-cppagent-mqtt: Header.testIndicator absent on MQTT Streams Header #131 — Header.testIndicator absent — another missing Header attribute cppagent emits.

References

• Source: libraries/MTConnect.NET-JSON-cppagent/Streams/JsonStreamsHeader.cs
• cppagent reference: test_package/json_printer_stream_test.cpp
• Evidence captures: current.json + cppagent-current.json