TrakHound Docs MTConnect.NET Compliance by Version

Compliance by Version

The MTConnect versions and wire formats MTConnect.NET supports, and how each is validated.
MTConnect.NET Docs Menu

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 versionReleased by MTConnectLibrary constantStreams XSDDevices XSDAssets XSDError XSD
v1.02008MTConnectVersions.Version10yesyesn/ayes
v1.12010MTConnectVersions.Version11yesyesn/ayes
v1.22012MTConnectVersions.Version12yesyesyesyes
v1.32014MTConnectVersions.Version13yesyesyesyes
v1.42017MTConnectVersions.Version14yesyesyesyes
v1.52018MTConnectVersions.Version15yesyesyesyes
v1.62019MTConnectVersions.Version16yesyesyesyes
v1.72020MTConnectVersions.Version17yesyesyesyes
v1.82020MTConnectVersions.Version18yesyesyesyes
v2.02021MTConnectVersions.Version20yesyesyesyes
v2.12022MTConnectVersions.Version21yesyesyesyes
v2.22023MTConnectVersions.Version22yesyesyesyes
v2.32024MTConnectVersions.Version23yesyesyesyes
v2.42024MTConnectVersions.Version24yesyesyesyes
v2.52025MTConnectVersions.Version25yesyesyesyes
v2.62025MTConnectVersions.Version26yesyesyesyes
v2.72025MTConnectVersions.Version27yesyesyesyes

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.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).
  • 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.

AttributeIntroduced atNotes
creationTimev1.0UTC ISO 8601.
senderv1.0agent hostname or configured value.
instanceIdv1.0agent's InstanceId; resets on a buffer wipe.
versionv1.0agent's software version (not the MTConnect spec version).
assetBufferSizev1.2matches the agent's assetBufferSize config.
assetCountv1.2live count of assets in the buffer.
bufferSizev1.0matches the agent's observationBufferSize config.
nextSequencev1.0next sequence the agent will assign.
firstSequencev1.0lowest sequence still in the buffer.
lastSequencev1.0highest sequence currently in the buffer.
schemaVersionv1.4the MTConnect spec version of the response (e.g. "2.5").
validationv1.7true if the agent validates incoming Devices against the XSD.
Hashv2.2SHA-1 over the model; consumers detect a model change without re-parsing.
deviceModelChangeTimev1.7timestamp 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:

  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 formatReferencePostureCodec class
XMLMTConnect<Envelope>_<version>.xsd from schemas.mtconnect.orgXSD-validated, every envelope, every version v1.0 — v2.7MTConnect.Formatters.Xml.XmlResponseDocumentFormatter
JSON v1Library-defined (no normative JSON Schema exists)Stable on the library, mirrors XML's object structureMTConnect.Formatters.JsonResponseDocumentFormatter
JSON-CPPAGENT (v2)cppagent's application/mtconnect+json outputByte-for-byte cppagent-parity (array-of-wrappers canonical shape)MTConnect.Formatters.JsonHttpResponseDocumentFormatter
JSON-CPPAGENT-MQTTcppagent's MQTT topic broker outputByte-for-byte cppagent-parity (per-DataItem topic shape)MTConnect.Formatters.JsonMqttResponseDocumentFormatter
SHDRPart_5.0 Network spec proseSpec-compliant; both as adapter producer and as adapter consumerMTConnect.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.0 mandated 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 formatcppagent v2.5+MTConnect.NETRound-trip parity?
XMLyesyesyes (XSD-validated both sides)
JSON v1no (cppagent never shipped JSON v1)yesn/a
JSON-CPPAGENT v2yesyesyes (golden-file byte-parity)
JSON-CPPAGENT-MQTTyesyesyes (golden-file byte-parity)
SHDRyesyesyes (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.