Skip to main content

Schemas

The MQTT API is defined by one AsyncAPI contract. Its JSON schemas define the structure and constraints of every message. The operation pages explain what each field means; this section documents the types that several messages share, and the rules for validating messages against the contract.

The Contract​

PropertyValue
TitleZebra Handheld RFID Reader (RFD40/RFD90) IoT Connector API
Version1.22.0
Contract file formatAsyncAPI 3.0.0, the standard format for describing event-driven APIs
Protocol the reader speaksMQTT 3.1.1
Payload schema dialectAsyncAPI Schema Object, a superset of JSON Schema Draft 07 (the AsyncAPI 3.0.0 default; no message sets schemaFormat)
Content typeapplication/json
DirectionStated from the reader's point of view: a receive_* operation is a command the reader receives, and a send_* operation is a message it publishes

This site does not publish the contract file for download.

Validation Rules​

Use a validator that supports JSON Schema Draft 07. These rules affect the results:

  • Messages are open. No message schema sets additionalProperties: false, so a validator accepts a member that the message does not define. A misspelled member name passes validation; check names against the operation page.
  • Requirements are unconditional. Each object has one required list, and no requirement depends on another member's value. For example, config_endpoint requires the same seven configuration members for every operation.
  • Formats are annotations. Draft 07 does not enforce format. Where the contract declares one, such as date-time on event timestamps, it declares no pattern to enforce the shape.
  • Events are identified by structure. No member names the event kind. See Events.
  • Some relations can't be expressed. For example, reconnectDelayMin must not exceed reconnectDelayMax. Check these relations in your own code; the pages that define the fields state them.
  • Some published examples don't validate. A few of the contract's own examples, carried unchanged from the IoT Connector API definition, fail the schema they illustrate — for example, subscribe topics without the required retain. The operation pages say so where it matters.

Validate commands before you publish them. If you validate what readers send, validate against the latest version of the contract, currently 1.22.0. Newer firmware traffic can fail against an older version, and version 1.22.0 also requires fields and drops values that earlier revisions allowed. See Versioning and Compatibility.

Annotations​

The contract uses one annotation keyword, default: the value the reader uses when you omit the member, where the contract states one. It declares no readOnly, writeOnly or deprecated members.

Contract Extensions​

The contract carries x-iotc-* extensions that validators ignore but that document behavior:

ExtensionWhereMeaning
x-iotc-response-codesinfo, and each command operationThe full code catalog, and the codes scoped to each command. See Response Codes.
x-iotc-idempotent, x-iotc-idempotent-basis, x-iotc-idempotent-refusal-codesEach command operationWhether repeating the command is safe, why, and which codes refuse a repeat. See Duplicates and Retries.
x-iotc-async-ackThe install_certificate, set_os and reboot repliesThe accept code (1) and the event, if any, that reports the outcome
x-iotc-examplesinfoHow many examples the contract carries, and which messages have none

Schema Pages​

PageContents
Common ObjectsThe command, response, and event envelopes, and the primitive string and number types
MQTT EndpointsThe endpoint configuration, MQTT client parameters, topic entries, TLS parameters, batching, and event configuration
dataEVTThe types that make up dataEVT
EnumerationsEvery enumeration used by more than one message, and where the others are defined
Reserved and Deprecated FieldsMembers and values to stop using, and members with no effect

Types that only one command or event uses, such as the operating-mode object, are documented on that operation's page.

In This Section​

Was this helpful?