mod_rest/README: Add a section describing the JSON mapping Mostly complete

author: Kim Alvefur <zash@zash.se>
date: Sat, 25 Jan 2020 01:31:49 +0100
parent: 3828:a8aa11cc351d
child: 3890:117a979ef930
--- a/mod_rest/README.markdown	Sat Jan 25 00:46:09 2020 +0100
+++ b/mod_rest/README.markdown	Sat Jan 25 01:31:49 2020 +0100
@@ -283,6 +283,98 @@
 Remember to set `rest_callback_content_type = "application/json"` for
 this to work.
 
+# JSON mapping
+
+This section describes the JSON mapping. It can't represent any possible
+stanza, for full flexibility use the XML mode.
+
+## Stanza basics
+
+`kind`
+:   String representing the kind of stanza, one of `"message"`,
+    `"presence"` or `"iq"`.
+
+`type`
+:   String with the type of stanza, appropriate values vary depending on
+    `kind`, see [RFC 6121]. E.g.`"chat"` for *message* stanzas etc.
+
+`to`
+:   String containing the XMPP Address of the destination / recipient of
+    the stanza.
+
+`from`
+:   String containing the XMPP Address of the sender the stanza.
+
+`id`
+:   String with a reasonably unique identifier for the stanza.
+
+## Basic Payloads
+
+### Messages
+
+`body`
+:   String, human readable text message.
+
+`subject`
+:   String, human readable summary equivalent to an email subject or the
+    chat room topic in a `type:groupchat` message.
+
+### Presence
+
+`show`
+:   String representing availability, e.g. `"away"`, `"dnd"`. No value
+    means a normal online status. See [RFC 6121] for the full list.
+
+`status`
+:   String with a human readable text message describing availability.
+
+## More payloads
+
+### Messages
+
+`state`
+:   String with current chat state, e.g. `"active"` (default) and
+    `"composing"` (typing).
+
+`html`
+:   String with HTML allowing rich formating. **MUST** be contained in a
+    `<body>` element.
+
+`oob_url`
+:   String with an URL of an external resource.
+
+### Presence
+
+`join`
+:   Boolean, used to join group chats.
+
+### IQ
+
+`ping`
+:   Boolean, a simple ping query. "Pongs" have only basic fields
+    presents.
+
+`version`
+:   Map with `name`, `version` fields, and optionally an `os` field, to
+    describe the software.
+
+#### Service Discovery
+
+`disco`
+
+:   Boolean `true` in a `kind:iq` `type:get` for a service discovery
+    query.
+
+    Responses have a map containing an array of available features in
+    the `features` key and an array of "identities" in the `identities`
+    key. Each identity has a `category` and `type` field as well as an
+    optional `name` field. See [XEP-0030] for further details.
+
+`items`
+:   Boolean `true` in a `kind:iq` `type:get` for a service discovery
+    items list query. The response contain an array of items like
+    `{"jid":"xmpp.address.here","name":"Description of item"}`.
+
 # Compatibility
 
 Requires Prosody trunk / 0.12
author	Kim Alvefur <zash@zash.se>
date	Sat, 25 Jan 2020 01:31:49 +0100
parent	3828:a8aa11cc351d
child	3890:117a979ef930