MQTT and Message Metadata
Version 1.0
Working Draft 01
01 July 2015
Technical Committee:
OASIS Message Queuing Telemetry Transport (MQTT) TC
Chairs:
Raphael J Cohn ([email protected]), Individual
Richard J Coppen ([email protected]), IBM
Editor:
Andrew Banks ([email protected]), IBM
Ian Craggs ([email protected]), IBM
Related work:
This document is related to:
 MQTT Version 3.1.1. Edited by Andrew Banks and Rahul Gupta. Latest
version: http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqttv3.1.1.html.
Abstract:
This document describes message formats used in MQTT.
Status:
This Working Draft (WD) has been produced by one or more TC Members;
it has not yet been voted on by the TC or approved as a Committee Note
Draft. The OASIS document Approval Process begins officially with a TC
vote to approve a WD as a Committee Note Draft. A TC may approve a
Working Draft, revise it, and re-approve it any number of times as a
Committee Note Draft.
URI patterns:
Initial publication URI:
http://docs.oasis-open.org/mqtt/msgfmts/v1.0/cnd01/msgfmts-v1.0cnd01.doc.
Permanent “Latest version” URI:
http://docs.oasis-open.org/mqtt/msgfmts/v1.0/msgfmts-v1.0.doc.
(Managed by OASIS TC Administration; please don’t modify.)
This is intended as a Non-Standards Track Work Product.
The patent provisions of the OASIS IPR Policy do not apply.
Copyright © OASIS Open 2015. All Rights Reserved.
All capitalized terms in the following text have the meanings assigned to them in the OASIS
Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the
OASIS website.
This document and translations of it may be copied and furnished to others, and derivative
works that comment on or otherwise explain it or assist in its implementation may be prepared,
copied, published, and distributed, in whole or in part, without restriction of any kind, provided
that the above copyright notice and this section are included on all such copies and derivative
works. However, this document itself may not be modified in any way, including by removing
the copyright notice or references to OASIS, except as needed for the purpose of developing any
document or deliverable produced by an OASIS Technical Committee (in which case the rules
applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to
translate it into languages other than English.
This document and the information contained herein is provided on an "AS IS" basis and OASIS
DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP
RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
PURPOSE.
msgmetadata-v1.0-wd01
Non-Standards Track
Working Draft 01
Copyright © OASIS Open 2015. All Rights Reserved.
01 July 2015
Page 2 of 10
[Type the document title]
The limited permissions granted above are perpetual and will not be revoked by OASIS or its
successors or assigns.
This is intended as a Non-Standards Track Work Product.
The patent provisions of the OASIS IPR Policy do not apply.
Table of Contents
1
Introduction ............................................................................................................................. 4
1.1 References (non-normative).................................................................................................. 4
1.2 Section Level 2 ....................................................................................................................... 4
1.2.1 Section Level 3 ................................................................................................................ 5
1.3 Section Level 2 ....................................................................................................................... 6
2
Heading .................................................................................................................................... 7
Appendix A.
Acknowledgments ................................................................................................... 8
Appendix B.
Some Appendix ........................................................................................................ 9
B.1.1 Sub-subsidiary Appendix Section.................................................................................... 9
Appendix C.
Revision History ..................................................................................................... 10
msgmetadata-v1.0-wd01
Non-Standards Track
Working Draft 01
Copyright © OASIS Open 2015. All Rights Reserved.
01 July 2015
Page 3 of 10
[Type the document title]
B.1 Subsidiary Appendix Section ................................................................................................. 9
This is intended as a Non-Standards Track Work Product.
The patent provisions of the OASIS IPR Policy do not apply.
1 Introduction
MQTT conveys compact but limited data about its messages. This committee note discusses the
need to extend the metadata associated with messages.
1.1 References (non-normative)
NOTE (remove this note and following examples before publication): The proper format for
citation of technical work produced by an OASIS TC (whether Standards Track or Non-Standards
Track) is:
Work Product title (italicized). Edited by Albert Alston, Bob Ballston, and Calvin Carlson.
Approval date (DD Month YYYY). OASIS Stage Identifier and Revision Number (e.g., OASIS
Committee Specification Draft 01). Principal URI (version-specific URI, e.g., with filename
component: .../csd01/somespec-v1.0-csd01.html). Latest version: (latest-version URI, without
stage identifiers).
For example:
[OpenDoc-1.2]
Open Document Format for Office Applications (OpenDocument) Version 1.2. Edited by Patrick
Durusau and Michael Brauer. 19 January 2011. OASIS Committee Specification Draft 07.
http://docs.oasis-open.org/office/v1.2/csd07/OpenDocument-v1.2-csd07.html. Latest version:
http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html.
1.2 Requirements
The data that is carried by MQTT as part of a message is currently limited to:
1. The message payload
2. The topic name of the message
3. The Qos of the message
4. Whether the message should be, or was retained by the server
5. Whether the message is a duplicate
6. Some messages carry a message identifier, but this is not usually useful to a producing
or consuming application
Examine some examples of metadata not already carried by MQTT and categorise the attributes
of the metadata.
msgmetadata-v1.0-wd01
Non-Standards Track
Working Draft 01
Copyright © OASIS Open 2015. All Rights Reserved.
01 July 2015
Page 4 of 10
[Type the document title]
[Citation Label]
This is intended as a Non-Standards Track Work Product.
The patent provisions of the OASIS IPR Policy do not apply.
1.2.1 Message payload type
MQTT messages are bytes. It has been proposed that some description of how to interpret the
bytes should be added to the protocol. For example this might indicate whether the bytes
represent a string or a number. The recipient of the message may choose to interpret the bytes
in a different ways by knowing what they represent.

The metadata should place no open ended capability on either the producer or
consumer of a message. It should be possible to write a producer or consumer client
application which fully supports every possible value of the metadata. So, for the
payload type it should be possible to write a generic consumer which can handle every
possible value of payload type.

The producer and consumer applications may operate successfully by only using a
subset of the metadata and by only allowing a subset of the possible values of the
metadata. For example the producer and consumer applications may expect to only
ever send String data.

Client and server implementations do not validate values of metadata that they do not
interpret. Consequently the consuming application may choose to validate that the data
it receives is the payload type claimed.

The producer and consumer applications may operate successfully without examining
the metadata. The producer and consumer could, for example, continue to send a String
as a set of bytes and not set or payload type to String, this would mean an intermediary
might not understand the payload.

The client or server implementation may not need to understand the metadata it is
passing between the producing and consuming clients. In this case the server must pass
the metadata unchanged between the producing and consuming clients. Consequently a
server cannot simply receive payload type String messages and emit them as payload
type bytes.
1.2.2 Time to live
Messages may be useful for a limited amount of time, for instance because they convey the
current temperature. System resources can be saved by discarding messages which are no
longer useful, as indicated by the time to live. If the server stores a message before delivering it
to a consumer it might reduce the time to live of the outbound message by the amount of time
that it is stored in the server. The receiver should never observe a value of the time to live which
is negative.

Message metadata which is interpreted by the client or server implementation must be
well defined such that it is possible to write a client or server implementation which
msgmetadata-v1.0-wd01
Non-Standards Track
Working Draft 01
Copyright © OASIS Open 2015. All Rights Reserved.
01 July 2015
Page 5 of 10
[Type the document title]
There are a large number of possible message types and it would be burdensome for an
application to have to support all possible types.
This is intended as a Non-Standards Track Work Product.
The patent provisions of the OASIS IPR Policy do not apply.
fully supports all types of metadata. So, the time to live must be defined such that it
always represents a practical amount of time, like a positive number of milliseconds.

Client or server implementations may safely ignore metadata if they wish to provide a
reduced implementation. A server might forward the time to live value to the consumer
unchanged and not actually expire the messages.

Client and server implementations should validate the values of metadata that they
interpret. For example, messages with a negative time to live should be rejected.

Server implementations should pass all metadata to the eventual consumers, however
the metadata passed on may not be exactly that which they received. The consumer
would always see a time to live value in the messages.
1.2.3 Correlator

The metadata may be relevant to only one message at a time. It must be possible to
determine which message the metadata relates to.

The client or server implementations should not need to store unbounded amounts of
metadata. The conditions under which the metadata can be safely discarded should be
well defined.
1.3 Section Level 2
msgmetadata-v1.0-wd01
Non-Standards Track
Working Draft 01
Copyright © OASIS Open 2015. All Rights Reserved.
01 July 2015
Page 6 of 10
[Type the document title]
In a request response messaging pattern the request message needs to carry a correlator so that
the responder can indicate which request it is responding to.
This is intended as a Non-Standards Track Work Product.
The patent provisions of the OASIS IPR Policy do not apply.
2 Heading
[Type the document title]
Text.
msgmetadata-v1.0-wd01
Non-Standards Track
Working Draft 01
Copyright © OASIS Open 2015. All Rights Reserved.
01 July 2015
Page 7 of 10
This is intended as a Non-Standards Track Work Product.
The patent provisions of the OASIS IPR Policy do not apply.
Appendix A. Acknowledgments
The following individuals have participated in the creation of this specification and are gratefully
acknowledged:
Participants:
[Type the document title]
[Participant Name, Affiliation | Individual Member]
[Participant Name, Affiliation | Individual Member]
msgmetadata-v1.0-wd01
Non-Standards Track
Working Draft 01
Copyright © OASIS Open 2015. All Rights Reserved.
01 July 2015
Page 8 of 10
This is intended as a Non-Standards Track Work Product.
The patent provisions of the OASIS IPR Policy do not apply.
Appendix B. Some Appendix
Text.
B.1 Subsidiary Appendix Section
Text.
B.1.1 Sub-subsidiary Appendix Section
[Type the document title]
text.
msgmetadata-v1.0-wd01
Non-Standards Track
Working Draft 01
Copyright © OASIS Open 2015. All Rights Reserved.
01 July 2015
Page 9 of 10
This is intended as a Non-Standards Track Work Product.
The patent provisions of the OASIS IPR Policy do not apply.
Appendix C.
Revision
Date
06 July 2015
Editor
Andrew Banks
Changes Made
Add requirements
[Type the document title]
1
Revision History
msgmetadata-v1.0-wd01
Non-Standards Track
Working Draft 01
Copyright © OASIS Open 2015. All Rights Reserved.
01 July 2015
Page 10 of 10