From a6a29421297c1e45ed3f560525965c9cbf354d51 Mon Sep 17 00:00:00 2001
From: Sam Whited <sam@samwhited.com>
Date: Wed, 22 Apr 2020 10:43:13 -0400
Subject: [PATCH] XEP-0389: better describe the type attribute

---
 xep-0389.xml | 34 ++++++++++++++++------------------
 1 file changed, 16 insertions(+), 18 deletions(-)

diff --git a/xep-0389.xml b/xep-0389.xml
index 36d08d9f..49cd178f 100644
--- a/xep-0389.xml
+++ b/xep-0389.xml
@@ -166,8 +166,8 @@
   </p>
   <p>
     For recovery or registration, the server MUST include a list of all
-    challenge types which the client may receive during the course of
-    registering or recovering an account.
+    challenges which the client may receive during the course of registering or
+    recovering an account.
     These are grouped into "flows" and let the client pick a registration
     workflow that only contains challenges which the client supports.
     Each &lt;flow/&gt; element MUST have a unique "id" attribute which is used
@@ -182,7 +182,7 @@
     representing the various challenges that must be completed to complete the
     registration or recovery flow.
     Each &lt;challenge/&gt; element contains a string that uniquely (within the
-    given parent element) identifies the type of challenge that will be offered.
+    given parent element) identifies the challenge that will be offered.
     If a flow would offer the same challenge twice (eg. two dataforms asking for
     different data), the challenge SHOULD only be listed once in the flow
     element.
@@ -264,12 +264,10 @@
     If replying to an IQ, the challenge must be wrapped in an IQ of type
     "result".
     Challenges take the form of a &lt;challenge/&gt; element qualified by the
-    'urn:xmpp:register:0' namespace with a 'type' attribute containing the
-    challenge type and containing a challenge data payload.
+    'urn:xmpp:register:0' namespace with a 'type' attribute that uniquely
+    identifies the type of payload a client might expect the element to contain.
   </p>
   <p>
-    Type type of a challenge is a value which identifes what sort of payload a
-    client might expect.
     This document defines a type of 'jabber:x:data' which MUST always contain a
     data form (an 'x' element with type 'form') as defined by &xep0004;.
     Other types may be defined in the future.
@@ -304,8 +302,8 @@
     sending a &lt;response/&gt; element qualified by the 'urn:xmpp:register:0'
     namespace or a cancellation as defined later in this document.
     If the client sends a response, it MUST also include a payload defined by
-    the specific challenge type.
-    In the case of a jabber:x:data challenge, the payload should be a form
+    the challenges 'type' element.
+    In the case of a "jabber:x:data" challenge, the payload should be a form
     submission as defined by &xep0004; (an 'x' element of type 'submit').
     For instance, to reply to the data form challenge from the previous example
     a client might send:
@@ -438,16 +436,16 @@
   <status>provisional</status>
 </ns>]]></code>
   </section2>
-  <section2 topic='IBR Challenge Types Registry' anchor='registrar-challenges'>
+  <section2 topic='IBR Challenges Registry' anchor='registrar-challenges'>
     <p>
-      The XMPP Registrar shall maintain a registry of IBR challenge types.
-      Challenge types defined within the XEP series MUST be registered with the
-      XMPP Registrar.
+      The XMPP Registrar shall maintain a registry of IBR challenges.
+      Challenges defined within the XEP series MUST be registered with the XMPP
+      Registrar.
     </p>
     &REGPROCESS;
     <code><![CDATA[
 <challenge>
-  <name>The name of the challenge (from the initial <challenge/> listing).</name>
+  <type>A name that uniquely identifies the challenge.</type>
   <desc>A natural-language summary of the challenge.</desc>
   <doc>
     The doucment (or documents) in which the IBR challenge and its paylaod are
@@ -459,18 +457,18 @@
   </p>
   </section2>
   <section2 topic='Challenge Types' anchor='registrar-ibrchallenges'>
-    <p>This specification defines the following IBR challenge types:</p>
+    <p>This specification defines the following IBR challenge:</p>
     <ul>
       <li>jabber:x:data</li>
     </ul>
     <p>
       Upon advancement of this specification from a status of Experimental to a
       status of Draft, the &REGISTRAR; shall add the following definition to the
-      IBR challenge types registry, as described in this document:
+      IBR challenges registry, as described in this document:
     </p>
-    <code caption='Challenge Type Registry Submission for Data Forms'><![CDATA[
+    <code caption='IBR Challenges Registry Submission for Data Forms'><![CDATA[
 <challenge>
-  <name>jabber:x:data</name>
+  <type>jabber:x:data</type>
   <desc>Requests that the client fill out an XEP-0004 data form.</desc>
   <doc>&xep0389;, &xep0004;</doc>
 </challenge>]]></code>