Versioning and Compatibility

Reference·Audience: API consumer·Use: judge whether a contract update can affect your integration, and find what is deprecated

The MQTT API is defined by one AsyncAPI contract. This page explains how that contract's version changes and how it marks fields and values that you should stop using.

The Contract Version

Property	Value
Title	Zebra Handheld RFID Reader (RFD40/RFD90) IoT Connector API
Identifier	urn:com:zebra:iotc:rfd40-90:mqtt
Version	1.22.0
Contract file format	AsyncAPI 3.0.0, the standard format for describing event-driven APIs, with payloads in the AsyncAPI Schema Object, a superset of JSON Schema Draft 07
Protocol the reader speaks	MQTT 3.1.1
Default content type	application/json

The contract version is the IoT Connector API version that the contract describes, V1.22. It is not the apiVersion that a reader reports in a reply, which can be lower. See API Version Support.

What a Minor Version May Change

The contract states no versioning policy. Until October 2026 it numbered its own revisions, and those revisions, 1.23.0 through 1.26.0, were additive or relaxing: nothing that a conforming client sent against the previous revision became invalid. They:

• admitted values that an earlier version rejected, for example a new enumeration member in a reply;
• stopped requiring members that an earlier version required;
• added optional members, bounds on previously unbounded fields, or documentation.

Two consequences follow for your integration:

• Check generated values against new bounds. When version 1.23.0 bounded previously unconstrained fields, such as tenantId at 48 characters, no published example became invalid, but a value your code generates might have.
• Replies and events can contain values your code has not seen. If you validate reader traffic against the contract, validate against the latest minor version.

Version 1.22.0 is different. The contract was regenerated from the IoT Connector API definition and took the API's version, so the number went down while the contract moved on. It also narrows what the contract accepts: it requires fields and drops values that earlier revisions allowed. Check your requests and your validation against it; the Changelog lists every change.

What a major or patch version may change is not specified in the available sources.

Where Changes Are Recorded

The contract carries no change history. The Changelog records what changed in each contract version.

How Deprecation Is Stated

The contract uses no deprecation keyword or extension: no member is marked deprecated, and no value is marked as an alias. Where a member is being retired, its description says so. Reserved and Deprecated Fields lists the members to stop relying on, the reserved members that have no effect, and the unsupported values.

A deprecation notice period, a removal schedule, and the version in which a deprecated item is removed are not specified in the available sources.

Names Removed from the Contract

The command names set_eth, cloud_connect, and config_alerts are no longer part of the contract. No message in version 1.22.0 carries them, and the contract describes no way to configure the Ethernet interface.

Related: 📕 API Version Support · 📕 Reserved and Deprecated Fields · 📕 Schemas

API Version Support

Four version identifiers appear in the MQTT API. They measure different things, so check which one a question needs before you rely on it.

Version Identifiers

Identifier	Where it appears	What it identifies
Contract version, currently 1.22.0	The AsyncAPI contract's info.version	The published message contract that this reference describes, numbered with the IoT Connector API version it describes, V1.22. See Versioning and Compatibility.
apiVersion	Command responses (not declared on delete_wifi_profile) and mqttConnEVT	The version reported by the command handler that produced the reply. See API Version Reporting.
readerVersion.detailedVersions.iotcVersion	The get_version response	The IoT Connector version on the reader.
readerVersion.firmwareVersion	The get_version response	The reader firmware build.

Values an apiVersion Can Take

Command responses carry apiVersion as a string from this set: V1.0, V1.1, V1.2, V1.21, V1.22. mqttConnEVT carries it as a JSON number, such as 1.21; its schema pairs type: number with the same string set, which no number can match. The full rules are on Enumerations.

What a Version Cannot Tell You

• Per-operation support. The contract declares one set of apiVersion values for every command. It does not state which version each command handler reports, or which operations each version supports. The Details section of each operation page shows an API version for that command; because the contract declares no per-command version, treat that value as informational, not as a constraint to validate against.
• Ordering. Don't compare apiVersion strings to decide which is newer. The contract defines no ordering for them.
• Firmware mapping. Which firmware build reports which apiVersion or iotcVersion is not specified in the available sources.

Related: 📕 Versioning and Compatibility · 📕 API Version Reporting · 📕 get_version