The JSON-CPPAGENT codec produces output that matches the cppagent reference implementation's JSON v2 format byte-for-byte.
The MTConnect Standard does not currently specify a JSON wire format via SysML XMI / XSD / prose; cppagent's src/printer/JsonPrinter.cpp is the de-facto specification.
This library's codec targets that reference so a consumer written against cppagent's JSON output works against an MTConnect.NET agent without per-implementation conditionals, and vice versa.
The format uses three structural idioms:
- Object-keyed top-level wrappers —
MTConnectStreams,MTConnectDevices,MTConnectAssets,MTConnectError— one per envelope kind. - Array-of-wrappers for ordered collections — Streams'
DeviceStream,ComponentStream, the per-category observation arrays (Events,Samples,Condition), and Assets' per-type containers (CuttingTool,File, …) all serialize as JSON arrays so order is preserved. - Object-keyed properties for attribute-style data —
Header, individual observation properties, asset measurement properties.
Document Format ID
The codec registers as JSON-cppagent in the formatter registry.
Codec Classes
| Class | Role |
|---|---|
MTConnect.Formatters.JsonHttpResponseDocumentFormatter | Top-level IResponseDocumentFormatter for the four envelope kinds. Returns application/json. |
MTConnect.Formatters.JsonHttpEntityFormatter | Per-entity formatter (single Observation, single Asset) for callers that splice individual entities into a larger document. |
MTConnect.Streams.Json.JsonStreamsResponseDocument | DTO that mirrors the MTConnectStreams envelope. |
MTConnect.Devices.Json.JsonDevicesResponseDocument | DTO that mirrors the MTConnectDevices envelope. |
MTConnect.Assets.Json.JsonAssetsResponseDocument | DTO that mirrors the MTConnectAssets envelope. |
MTConnect.Streams.Json.JsonDeviceStream / JsonComponentStream | Per-device + per-component stream containers. |
MTConnect.Streams.Json.JsonObservation | Base shape for every observation under Events, Samples, and Condition. |
MTConnect.JsonFunctions | Serializer options bundle (default vs indented) shared across the codec. |
Sample Envelope
The codec's output for a /current request demonstrates every idiom — the top-level MTConnectStreams wrapper, the jsonVersion: 2 marker, the Header object, and the array-of-wrappers shape for DeviceStream, ComponentStream, and the per-DataItem observation arrays (AdapterUri, ConnectionStatus, etc.).
{
"MTConnectStreams": {
"jsonVersion": 2,
"schemaVersion": "2.0",
"Header": {
"instanceId": 1702144894,
"version": "6.0.1.0",
"sender": "DESKTOP-HV74M4N",
"bufferSize": 150000,
"firstSequence": 1,
"lastSequence": 246,
"nextSequence": 247,
"deviceModelChangeTime": "2023-12-09T18:01:38.0133172Z",
"creationTime": "2023-12-10T03:06:48.4086283Z"
},
"Streams": {
"DeviceStream": [
{
"name": "agent",
"uuid": "b85fa5f1-bc29-40e0-9893-c8ef8eac6761",
"ComponentStream": [
{
"component": "Adapter",
"componentId": "adapter_shdr_56697b5624",
"name": "adapterShdr",
"Events": {
"AdapterUri": [
{
"value": "shdr://localhost:7878",
"dataItemId": "adapter_shdr_56697b5624_adapterUri",
"name": "adapterUri",
"timestamp": "2023-12-09T18:01:39.8259158Z",
"sequence": 243
}
],
"ConnectionStatus": [
{
"value": "LISTEN",
"dataItemId": "adapter_shdr_56697b5624_connectionStatus",
"name": "connectionStatus",
"timestamp": "2023-12-09T18:01:52.1224823Z",
"sequence": 246
}
]
}
}
]
}
]
}
}
}
The fixture is libraries/MTConnect.NET-JSON-cppagent/Examples/MTConnectStreamsResponseDocument.json.
Assets and Devices envelopes follow the same envelope-wrapper + array-of-types pattern; the assets sample under the same Examples/ directory shows the per-type containers (CuttingTool, File, …) holding asset arrays.
Spec-Version Compatibility
cppagent's JSON v2 codec covers the same MTConnect data model as the XML codec, so the version coverage matches the XML page's table where the codec is implemented.
The library currently targets MTConnect versions up to v2.5 (see MTConnectVersions.Max); the NuGet package's description states the same upper bound.
| Spec version | Status in this library | Notes |
|---|---|---|
| v1.0 – v1.8 | Read + write. | The codec emits the same JSON shape regardless of MTConnect version; the version surfaces on the document via schemaVersion. |
| v2.0 – v2.5 | Read + write. | Default + canonical target. |
| v2.6 – v2.7 | Codec shape unchanged; new type-system additions (e.g. Pallet rich measurements) are tracked in Compliance by Version. | cppagent has continued to evolve its emitted JSON across these releases; Known Divergences lists every observed difference. |
The jsonVersion field on the envelope is fixed at 2 for this codec.
A future JSON v3 codec, should one land, would carry jsonVersion: 3; consumers gate on that value to pick a parser.
The reference implementation is at mtconnect/cppagent; the normative MTConnect Standard for the type-system data the JSON carries is the SysML XMI at mtconnect/mtconnect_sysml_model and the XSDs at schemas.mtconnect.org (the XSDs pin XML wire shape; the JSON codec mirrors the same field set without inheriting the XML attribute-vs-element distinction).
Request Flow
- Consumer HTTP module
GET /currentwithAccept: application/json - HTTP moduleResolves the device and path to an
IStreamsResponseOutputDocument - HTTP module Formatter
Format(document, options) - FormatterProjects the document to a
JsonStreamsResponseDocumentDTO, and applies the indent option from the query string - Formatter System.Text.Json
JsonSerializer.Serialize(stream, dto, options)writes the stream - Formatter HTTP module
FormatWriteResult(stream, "application/json") - HTTP module Consumer
200 OKwith anapplication/jsonbody
Reads run the same pipeline in reverse via JsonHttpResponseDocumentFormatter.CreateStreamsResponseDocument (and the matching Devices / Assets methods):
System.Text.Json deserializes into the Json*ResponseDocument DTOs, which then project back to the canonical IStreamsResponseDocument / IDevicesResponseDocument / IAssetsResponseDocument interfaces the rest of the library consumes.
Caveats and Known Divergences
- No normative spec. The MTConnect Standard does not specify a JSON wire format.
The de-facto reference is cppagent's
JsonPrinter; Known Divergences tracks any divergence between this library's output and that reference. - Field ordering inside objects is not load-bearing. JSON object keys are unordered by specification. The codec emits them in DTO-declaration order for diff-readability against the cppagent reference, but a consumer that gates on key order is non-conformant to RFC 8259.
- Array order is load-bearing. Arrays in this codec (
DeviceStream,ComponentStream, the per-DataItem observation arrays underEvents/Samples/Condition, the per-type asset arrays) preserve insertion order. Consumers that re-order arrays on parse will mis-render time-series data and condition transitions. - Single-element collections still serialize as arrays. Even when only one
DeviceStreamis present, the field is"DeviceStream": [ { … } ]. This matches cppagent and lets a consumer parse with a single shape regardless of cardinality; consumers must not special-case the 1-element case. UNAVAILABLEis the canonical sentinel for missing observations. The codec emits"value": "UNAVAILABLE"(a string) rather thannullor an absent field, matching cppagent.schemaVersionis a string, not a number. The field carries"2.0","2.5", etc. — never2.0as a JSON number. Older toolchains that strip the quotes will round-trip to a different shape.- Round-trip is asymmetric for some Asset subtypes. The codec serializes every shipped asset type, but read-path coverage lags for assets that the agent doesn't ingest as a primary type (e.g. legacy QIF-wrapped payloads). Compliance by Version lists which asset types round-trip cleanly.
- Indentation is request-time selectable. Passing
indentOutput=truein the formatter options (orpretty=trueon an HTTP query string, depending on the agent module) switches to the indentedSystem.Text.Jsonprofile. The default is compact output, matching cppagent's default.
See Also
MTConnect.NET-JSON-cppagentlibrary README — package install + per-version notes.- JSON-CPPAGENT-MQTT — the same envelope shape published over MQTT topics.
- JSON v1 — the legacy JSON codec.
- XML — the canonical, XSD-pinned wire format.
- cppagent
JsonPrintersource — the reference implementation this codec mirrors. - Compliance by Version — JSON-CPPAGENT vs cppagent reference parity matrix and divergence ledger.