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).
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.Modelintroduced. - v1.3:
Referenceselement on Components;Configurationelement under Components. - v1.4:
Compositionships as a first-class element under Components;Specificationelement;Constraintson DataItems;Filterelement on DataItems. - v1.5:
DATA_SETrepresentation introduced;DataItemRelationshipintroduced;ComponentRelationshipintroduced. - v1.6:
TABLErepresentation introduced;CoordinateSystemelement introduced (deprecating thecoordinateSystemenum);Resetelement. - v1.7:
Agent self-describing
AgentDevice introduced;SpecificationRelationship;PEERComponentRelationshiptype;MTConnectVersionattribute on Device. - v1.8:
coordinateSystemIdRefattribute on DataItem. - v2.0:
DATA_SETbecomes the canonical representation for several types (PART_COUNT,ASSET_COUNT); MQTT topic templates introduced in the spec'sPart_5(Network). - v2.1: extended
Qualityenum entries. - v2.2:
Hashattribute on Header and on Device;ComponentConfigurationParametersAsset. - v2.3:
Qualityfield on Observation made first-class. - v2.4:
Rich-template Pallet measurements (
HeightMeasurement,WidthMeasurement,LoadedHeightMeasurement, etc.) replace free-formMeasurement. - v2.5: spec-internal cleanup; no new wire-format-visible types.
- v2.6: per the spec's
Part_3cleanup; v2.6 SysML XMI is byte-identical to v2.7 per the spec's own publication (see 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).
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);
SysML Header class (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:
- If the request URL carries a
?version=parameter, the agent uses that. - Otherwise the agent uses the configured
defaultVersionfromagent.config.yaml. - 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 | 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.
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).
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 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 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); 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 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.
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 and MqttBroker 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.
SHDR
The SHDR protocol is the legacy text-line adapter protocol described in Part_5.0 Network of the MTConnect Standard (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.0mandated SHDR connection lifecycle (PING / PONG, asterisk heartbeat).
Documented at 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), 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 — how every claim above is grounded in an XMI / XSD / prose citation.
- Known divergences — where the standard contradicts itself and how the library handles each case.
- Test harness — how to run the compliance tier locally.
- Wire formats — per-format envelope shapes and sample payloads.