# Compliance by Version

> The MTConnect versions and wire formats MTConnect.NET supports, and how each is validated.

URL: https://www.trakhound.com/docs/mtconnect-net/compliance/per-version-matrix

`MTConnect.NET` is built against the MTConnect Standard from v1.0 through v2.7, and ships five wire formats. Every shipped envelope — Devices, Streams, Assets, Error — validates against the corresponding XSD at every version listed below, and every spec-defined type that appears at a given version is present in the library at that version, gated by the type's `MinimumVersion` / `MaximumVersion` metadata. Each wire format's on-the-wire shape is validated against an authoritative source: an XSD for XML, the cppagent reference for the v2 JSON codecs, and the spec prose for the SHDR adapter protocol. This page covers both axes: which spec versions are supported, and each format's compliance posture — byte-for-byte parity with the reference, partial parity, or intentional divergence — with the test fixtures and source files that pin the claim.

## Spec Versions Supported

The library tracks every published MTConnect spec version. The version constants live in `MTConnect.MTConnectVersions`, and `MTConnectVersions.Max` advertises the latest one the library can serialize for.

| MTConnect version | Released by MTConnect | Library constant | Streams XSD | Devices XSD | Assets XSD | Error XSD |
| --- | --- | --- | --- | --- | --- | --- |
| v1.0 | 2008 | `MTConnectVersions.Version10` | yes | yes | n/a | yes |
| v1.1 | 2010 | `MTConnectVersions.Version11` | yes | yes | n/a | yes |
| v1.2 | 2012 | `MTConnectVersions.Version12` | yes | yes | yes | yes |
| v1.3 | 2014 | `MTConnectVersions.Version13` | yes | yes | yes | yes |
| v1.4 | 2017 | `MTConnectVersions.Version14` | yes | yes | yes | yes |
| v1.5 | 2018 | `MTConnectVersions.Version15` | yes | yes | yes | yes |
| v1.6 | 2019 | `MTConnectVersions.Version16` | yes | yes | yes | yes |
| v1.7 | 2020 | `MTConnectVersions.Version17` | yes | yes | yes | yes |
| v1.8 | 2020 | `MTConnectVersions.Version18` | yes | yes | yes | yes |
| v2.0 | 2021 | `MTConnectVersions.Version20` | yes | yes | yes | yes |
| v2.1 | 2022 | `MTConnectVersions.Version21` | yes | yes | yes | yes |
| v2.2 | 2023 | `MTConnectVersions.Version22` | yes | yes | yes | yes |
| v2.3 | 2024 | `MTConnectVersions.Version23` | yes | yes | yes | yes |
| v2.4 | 2024 | `MTConnectVersions.Version24` | yes | yes | yes | yes |
| v2.5 | 2025 | `MTConnectVersions.Version25` | yes | yes | yes | yes |
| v2.6 | 2025 | `MTConnectVersions.Version26` | yes | yes | yes | yes |
| v2.7 | 2025 | `MTConnectVersions.Version27` | yes | yes | yes | yes |

Assets are not part of the v1.0 / v1.1 envelope set; the Assets envelope enters at v1.2 per the spec's XSD release history ([schemas.mtconnect.org](https://schemas.mtconnect.org/)).

Note: v1.9 was never released — the MTConnect Standard's version numbering jumped from v1.8 to v2.0. The library matches: no `Version19` constant exists.

## Per-Envelope Semantics

Each cell in the matrix above means: the agent can be asked to emit the named envelope at the named spec version, and the output validates against the matching `MTConnect<Envelope>_<version>.xsd` schema published by the standard body. The version-aware serializers (`Device.Process`, `DataItem.Process`, `Composition.Process`, and the per-envelope JSON / XML codecs) prune properties, DataItems, Components, and Assets whose `MinimumVersion` is above the target version, and prune any whose `MaximumVersion` is below it.

## Type Introduction Inventory

A subset of spec-version-introduced types the matrix tracks (every type carries its own `MinimumVersion` and `MaximumVersion`, generated from the SysML `introducedAtVersion` tag):

- **v1.2**: Assets envelope; `Description.Model` introduced.
- **v1.3**: `References` element on Components; `Configuration` element under Components.
- **v1.4**: `Composition` ships as a first-class element under Components; `Specification` element; `Constraints` on DataItems; `Filter` element on DataItems.
- **v1.5**: `DATA_SET` representation introduced; `DataItemRelationship` introduced; `ComponentRelationship` introduced.
- **v1.6**: `TABLE` representation introduced; `CoordinateSystem` element introduced (deprecating the `coordinateSystem` enum); `Reset` element.
- **v1.7**: Agent self-describing `Agent` Device introduced; `SpecificationRelationship`; `PEER` `ComponentRelationship` type; `MTConnectVersion` attribute on Device.
- **v1.8**: `coordinateSystemIdRef` attribute on DataItem.
- **v2.0**: `DATA_SET` becomes the canonical representation for several types (`PART_COUNT`, `ASSET_COUNT`); MQTT topic templates introduced in the spec's `Part_5` (Network).
- **v2.1**: extended `Quality` enum entries.
- **v2.2**: `Hash` attribute on Header and on Device; `ComponentConfigurationParameters` Asset.
- **v2.3**: `Quality` field on Observation made first-class.
- **v2.4**: Rich-template Pallet measurements (`HeightMeasurement`, `WidthMeasurement`, `LoadedHeightMeasurement`, etc.) replace free-form `Measurement`.
- **v2.5**: spec-internal cleanup; no new wire-format-visible types.
- **v2.6**: per the spec's `Part_3` cleanup; v2.6 SysML XMI is byte-identical to v2.7 per the spec's own publication (see [Compliance: Known divergences](https://www.trakhound.com/docs/mtconnect-net/compliance/known-divergences)).
- **v2.7**: spec cleanup; multiple minor enum and attribute additions.

Every introduction is auditable through the generated `.g.cs` files under `libraries/MTConnect.NET-Common/`, which carry the per-type `MinimumVersion` value sourced from the SysML model's `introducedAtVersion` ([`mtconnect/mtconnect_sysml_model`](https://github.com/mtconnect/mtconnect_sysml_model)).

## Header Fields per Version

The `Header` element gains attributes over time. The library populates them based on the target version; the `MTConnectAgentInformation` class is the source.

| Attribute | Introduced at | Notes |
| --- | --- | --- |
| `creationTime` | v1.0 | UTC ISO 8601. |
| `sender` | v1.0 | agent hostname or configured value. |
| `instanceId` | v1.0 | agent's `InstanceId`; resets on a buffer wipe. |
| `version` | v1.0 | agent's software version (not the MTConnect spec version). |
| `assetBufferSize` | v1.2 | matches the agent's `assetBufferSize` config. |
| `assetCount` | v1.2 | live count of assets in the buffer. |
| `bufferSize` | v1.0 | matches the agent's `observationBufferSize` config. |
| `nextSequence` | v1.0 | next sequence the agent will assign. |
| `firstSequence` | v1.0 | lowest sequence still in the buffer. |
| `lastSequence` | v1.0 | highest sequence currently in the buffer. |
| `schemaVersion` | v1.4 | the MTConnect spec version of the response (e.g. `"2.5"`). |
| `validation` | v1.7 | true if the agent validates incoming Devices against the XSD. |
| `Hash` | v2.2 | SHA-1 over the model; consumers detect a model change without re-parsing. |
| `deviceModelChangeTime` | v1.7 | timestamp of the last model change. |

Source: `MTConnectStreams_<version>.xsd` element `MTConnectStreamsType/Header` ([schemas.mtconnect.org](https://schemas.mtconnect.org/)); SysML `Header` class ([`mtconnect/mtconnect_sysml_model`](https://github.com/mtconnect/mtconnect_sysml_model)).

## How the Agent Picks a Version

When a consumer queries `/probe`, `/current`, `/sample`, or `/asset`, the agent picks the response version as follows:

1. If the request URL carries a `?version=` parameter, the agent uses that.
2. Otherwise the agent uses the configured `defaultVersion` from `agent.config.yaml`.
3. If neither is set, the agent uses `MTConnectVersions.Max`.

Requesting a version older than `MTConnectVersions.Version10` returns an Error envelope; requesting a version newer than `Max` returns an Error envelope as well.

## Wire Formats

Each wire format, the reference it is checked against, and its compliance posture:

| Wire format | Reference | Posture | Codec class |
| --- | --- | --- | --- |
| XML | `MTConnect<Envelope>_<version>.xsd` from [schemas.mtconnect.org](https://schemas.mtconnect.org/) | XSD-validated, every envelope, every version v1.0 — v2.7 | `MTConnect.Formatters.Xml.XmlResponseDocumentFormatter` |
| JSON v1 | Library-defined (no normative JSON Schema exists) | Stable on the library, mirrors XML's object structure | `MTConnect.Formatters.JsonResponseDocumentFormatter` |
| JSON-CPPAGENT (v2) | cppagent's `application/mtconnect+json` output | Byte-for-byte cppagent-parity (array-of-wrappers canonical shape) | `MTConnect.Formatters.JsonHttpResponseDocumentFormatter` |
| JSON-CPPAGENT-MQTT | cppagent's MQTT topic broker output | Byte-for-byte cppagent-parity (per-DataItem topic shape) | `MTConnect.Formatters.JsonMqttResponseDocumentFormatter` |
| SHDR | `Part_5.0` Network spec prose | Spec-compliant; both as adapter producer and as adapter consumer | `MTConnect.Adapters.ShdrAdapter` |

## XML

The XML output of every Streams / Devices / Assets / Error envelope validates against the matching `MTConnect<Envelope>_<version>.xsd` schema from [schemas.mtconnect.org](https://schemas.mtconnect.org/). The compliance test harness loads each shipped XSD as an embedded resource and validates a battery of golden-file fixtures against it (see [Test harness](https://github.com/TrakHound/MTConnect.NET/blob/master/contributing/compliance/test-harness.md)). The XSDs are vendored unchanged into the test project, byte-identical to the upstream copies. Formatter pass: `MTConnect.Formatters.Xml.XmlResponseDocumentFormatter` indents its output when the `indentOutput` formatter option is set; the HTTP server sets it from the `indentOutput` flag on its configuration, which defaults to `true`.

The library's XSD validator deliberately uses a permissive parser configuration to remain cross-platform. The .NET BCL ships an XSD 1.0 validator; a small set of XSD 1.1-only assertions in the published schemas (such as `xs:assert` for the `representation` enum) are not enforced at parse time, but the library injects the equivalent runtime checks. See [Troubleshooting: XSD validation failures](https://www.trakhound.com/docs/mtconnect-net/troubleshooting/xsd-validation-failures) for the diagnostic pattern when a model fails validation locally that succeeded against an XSD 1.1 validator.

## JSON v1

JSON v1 is `MTConnect.NET`'s in-house JSON shape, predating the MTConnect Standard's adoption of a JSON wire format. It mirrors the XML object structure one-to-one — `<Streams>` becomes `Streams`, every attribute becomes a field, every nested element becomes a nested object. The format is documented under [Wire formats](https://www.trakhound.com/docs/mtconnect-net/wire-formats) and remains a supported output for consumers that depend on it. The MTConnect Standard does not declare a normative JSON Schema (the JSON wire format in `Part_5` is descriptive prose, not a normative schema — see [Redmine #3889](https://projects.mtconnect.org/issues/3889)); the library's JSON v1 codec is the canonical shape against itself and is regression-tested with golden fixtures.

## JSON-CPPAGENT (v2)

The JSON-CPPAGENT codec is the library's byte-for-byte parity target with the [cppagent](https://github.com/mtconnect/cppagent) reference implementation's `application/mtconnect+json` output. The canonical shape is an array of single-key wrappers — each observation is wrapped in `{"<type>": {...}}` — which the cppagent v2 codec adopted in 2023.

The wire-shape tests live in `tests/MTConnect.NET-JSON-cppagent-Tests/` (Streams, Devices, Assets, and Formatters suites, plus end-to-end tests that pin the array-of-wrappers shape against `MTConnect.NET`'s output). A successful run is the gate that any consumer parsing cppagent's output can swap in `MTConnect.NET`'s agent and observe no change.

Documented at [Wire formats: JSON-CPPAGENT](https://www.trakhound.com/docs/mtconnect-net/wire-formats/json-v2-cppagent).

## JSON-CPPAGENT-MQTT

The JSON-CPPAGENT-MQTT codec is the per-DataItem MQTT topic broker shape: every DataItem publishes to a topic of the form `<prefix>/Device/<deviceUuid>/<dataItemId>` with a JSON-CPPAGENT-formatted payload. The cppagent reference's MQTT broker (introduced in cppagent v2) defines the topic template; `MTConnect.NET`'s [MqttRelay](https://www.trakhound.com/docs/mtconnect-net/modules/mqtt-relay) and [MqttBroker](https://www.trakhound.com/docs/mtconnect-net/modules/mqtt-broker) modules both speak this format.

Compliance is enforced by golden-file fixtures of cppagent's published MQTT output and round-trip parity tests. Documented at [Wire formats: JSON-CPPAGENT-MQTT](https://www.trakhound.com/docs/mtconnect-net/wire-formats/json-v2-cppagent-mqtt).

## SHDR

The SHDR protocol is the legacy text-line adapter protocol described in `Part_5.0` Network of the MTConnect Standard ([docs.mtconnect.org](https://docs.mtconnect.org/)). A line is `timestamp|dataItemKey|value` with subsequent `|key|value` repeats for compound observations. `MTConnect.NET` implements SHDR both as an adapter (the agent reads SHDR lines from a TCP socket) and as a producer (the standalone adapter app emits SHDR lines from a custom data source).

Compliance is enforced by:

- A round-trip parser test against every example line in `Part_5.0`'s prose (each test fixture cites the spec section it pins).
- A heartbeat-and-reconnect state-machine test against the `Part_5.0` mandated SHDR connection lifecycle (PING / PONG, asterisk heartbeat).

Documented at [Wire formats: SHDR](https://www.trakhound.com/docs/mtconnect-net/wire-formats/shdr).

## Variants of "Compliant"

Three claim levels on this page:

- **XSD-validated** — for XML envelopes. The output is fed through the matching XSD; a parse-clean result is sufficient.
- **Byte-for-byte parity** — for the JSON-CPPAGENT and JSON-CPPAGENT-MQTT codecs. The output is byte-compared against a captured cppagent reference output of the same model.
- **Spec-compliant prose** — for SHDR. The behavior is exercised against test fixtures that pin the spec's stated examples and state machines.

Each claim is auditable: the test fixtures cite the source ([Compliance: Spec cross-references](https://github.com/TrakHound/MTConnect.NET/blob/master/contributing/compliance/spec-cross-references.md)), and the test harness records pass / fail per claim level.

## Cross-Implementation Matrix

A consumer asks "will this work against MTConnect.NET the same way it works against cppagent?" The answer:

| Wire format | cppagent v2.5+ | MTConnect.NET | Round-trip parity? |
| --- | --- | --- | --- |
| XML | yes | yes | yes (XSD-validated both sides) |
| JSON v1 | no (cppagent never shipped JSON v1) | yes | n/a |
| JSON-CPPAGENT v2 | yes | yes | yes (golden-file byte-parity) |
| JSON-CPPAGENT-MQTT | yes | yes | yes (golden-file byte-parity) |
| SHDR | yes | yes | yes (per `Part_5.0` prose) |

## Where to Next

- [Spec cross-references](https://github.com/TrakHound/MTConnect.NET/blob/master/contributing/compliance/spec-cross-references.md) — how every claim above is grounded in an XMI / XSD / prose citation.
- [Known divergences](https://www.trakhound.com/docs/mtconnect-net/compliance/known-divergences) — where the standard contradicts itself and how the library handles each case.
- [Test harness](https://github.com/TrakHound/MTConnect.NET/blob/master/contributing/compliance/test-harness.md) — how to run the compliance tier locally.
- [Wire formats](https://www.trakhound.com/docs/mtconnect-net/wire-formats) — per-format envelope shapes and sample payloads.
