# Wire Formats Overview

> The formats MTConnect.NET reads and writes, and how to choose one.

URL: https://www.trakhound.com/docs/mtconnect-net/wire-formats

`MTConnect.NET` ships codecs for every wire format the MTConnect Standard recognizes, plus the SHDR adapter protocol that feeds the agent from upstream. These pages are the codec-level reference — sample envelopes, codec class names, spec-version compatibility, and how a request or message flows through each codec.

## The Formats

- **[XML](https://www.trakhound.com/docs/mtconnect-net/wire-formats/xml)** — the canonical wire format defined by the per-version XSDs (`MTConnectStreams_<ver>.xsd`, `MTConnectDevices_<ver>.xsd`, `MTConnectAssets_<ver>.xsd`, `MTConnectError_<ver>.xsd`). Codec lives in `MTConnect.NET-XML`. Validated at write-time against the corresponding XSD.
- **JSON v1** — the legacy MTConnect.NET JSON codec (document format `JSON`), object-keyed everywhere and mirroring the XML structure one-to-one. Pre-dates the MTConnect Standard's JSON format and the cppagent JSON v2 codec; shipped for compatibility with consumers built against early MTConnect.NET releases. New consumers should use JSON-CPPAGENT v2. Codec lives in `MTConnect.NET-JSON`.
- **[JSON-CPPAGENT (v2)](https://www.trakhound.com/docs/mtconnect-net/wire-formats/json-v2-cppagent)** — the cppagent reference's current JSON codec. Array-of-wrappers where order matters; object-keyed where it doesn't. Byte-for-byte cppagent parity is the library's compliance target. Codec lives in `MTConnect.NET-JSON-cppagent`.
- **[JSON-CPPAGENT-MQTT](https://www.trakhound.com/docs/mtconnect-net/wire-formats/json-v2-cppagent-mqtt)** — JSON-CPPAGENT v2 envelopes published over MQTT topics with a documented topic tree. Codec lives in `MTConnect.NET-JSON-cppagent` plus the `MTConnect.NET-MQTT` transport layer.
- **[MQTT topic protocol](https://www.trakhound.com/docs/mtconnect-net/wire-formats/mqtt)** — the MTConnect.NET topic structure for accessing agents, devices, observations and assets over MQTT. Lives in `MTConnect.NET-MQTT`.
- **[SHDR](https://www.trakhound.com/docs/mtconnect-net/wire-formats/shdr)** — the Simple Hierarchical Data Representation; the line-oriented adapter protocol that ships values from a PLC reader into the agent. Codec lives in `MTConnect.NET-SHDR`.

## Picking a Format

Diagram: To choose a format, first decide whether you are building a consumer or an adapter. An adapter uses SHDR. A consumer for a dashboard or browser uses XML; a modern .NET, Python, or Node consumer uses JSON-CPPAGENT v2; an MQTT subscriber uses JSON-CPPAGENT-MQTT; and a legacy consumer built only for MTConnect.NET uses JSON v1.

- Pulling data into a dashboard? XML is the canonical format and every consumer can read it.
- Building a modern consumer in any non-browser runtime? Use JSON-CPPAGENT v2 — it's the cppagent-parity format and the spec's current direction.
- Subscribing to a stream over MQTT? Use JSON-CPPAGENT-MQTT.
- Maintaining an old consumer built before the JSON v2 codec landed? JSON v1 still ships.
- Feeding the agent from upstream equipment? Use SHDR if your reader speaks it; the MQTT adapter and HTTP adapter are alternatives.

## Spec-Version Compatibility

Every wire-format page lists the MTConnect spec versions the format is conformant for, along with the per-version differences (new envelope types, new attributes, deprecated fields). The agent emits the wire format that matches the spec version the consumer requests.

## Round-Tripping

Every codec in `MTConnect.NET` is symmetric — it both reads and writes its format. Consumers can read agent output, modify it, and re-emit it without information loss. The per-codec test suites assert round-trip identity against fixtures generated from the SysML model and against captures from the cppagent reference.

## See Also

- [Compliance by Version](https://www.trakhound.com/docs/mtconnect-net/compliance/per-version-matrix#wire-formats) — the wire-format compliance matrix and the known divergences from the cppagent reference, with justifications.
- [Configure & Use](https://www.trakhound.com/docs/mtconnect-net#configure) — how to enable each wire format on the agent and the adapter.
- The NuGet packages [`MTConnect.NET-XML`](https://www.nuget.org/packages/MTConnect.NET-XML), [`MTConnect.NET-JSON-cppagent`](https://www.nuget.org/packages/MTConnect.NET-JSON-cppagent), and [`MTConnect.NET-SHDR`](https://www.nuget.org/packages/MTConnect.NET-SHDR) — the codec classes (`MTConnectXmlSerializer`, `MTConnectJsonSerializer`, `MTConnectCppAgentJsonSerializer`, `ShdrLine`, …) and their public surface.
