diff --git a/doc/zmq_msg_gets.txt b/doc/zmq_msg_gets.txt
index f7a92e3e..f887b407 100644
--- a/doc/zmq_msg_gets.txt
+++ b/doc/zmq_msg_gets.txt
@@ -20,10 +20,12 @@ the 'message' argument. Both the 'property' argument and the 'value'
 shall be NULL-terminated UTF8-encoded strings.
 
 Metadata is defined on a per-connection basis during the ZeroMQ connection
-handshake as specified in <rfc.zeromq.org/spec:37>.
+handshake as specified in <rfc.zeromq.org/spec:37>. Applications can set
+metadata properties using linkzmq:zmq_setsockopt[3] option ZMQ_METADATA.
+Application metadata properties must be prefixed with 'X-'.
 
-The following ZMTP properties can be retrieved with the _zmq_msg_gets()_
-function:
+In addition to application metadata, the following ZMTP properties can be
+retrieved with the _zmq_msg_gets()_ function:
 
     Socket-Type
     Routing-Id
@@ -73,7 +75,7 @@ zmq_msg_close (&msg);
 SEE ALSO
 --------
 linkzmq:zmq[7]
-
+linkzmq:zmq_setsockopt[3]
 
 AUTHORS
 -------
diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt
index e3d6ac7e..112d5759 100644
--- a/doc/zmq_setsockopt.txt
+++ b/doc/zmq_setsockopt.txt
@@ -469,6 +469,26 @@ Default value:: -1
 Applicable socket types:: all
 
 
+ZMQ_METADATA: Add application metadata properties to a socket
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The _ZMQ_METADATA_ option shall add application metadata to the specified _socket_,
+the metadata is exchanged with peers during connection setup. A metadata property is
+specfied as a string, delimited by a colon, starting with the metadata _property_
+followed by the metadata value, for example "X-key:value".
+_Property_ names are restrited to maximum 255 characters and must be prefixed by "X-".
+Multiple application metadata properties can be added to a socket by executing zmq_setsockopt()
+multiple times. As the argument is a null-terminated string, binary data must be encoded
+before it is added e.g. using Z85 (linkzmq:zmq_z85_encode[3]).
+
+NOTE: in DRAFT state, not yet available in stable releases.
+
+[horizontal]
+Option value type:: character string
+Option value unit:: N/A
+Default value:: not set
+Applicable socket types:: all
+
+
 ZMQ_MULTICAST_HOPS: Maximum network hops for multicast packets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Sets the time-to-live field in every multicast packet sent from this socket.