XEP-0215: Try resolving some ambiguities

XEP-0215: Add Lance as Co-Author, Bump namespace

XEP-0215: Add revision notes

xep-0215.xml

@@ -23,6 +23,21 @@
   &stpeter;
   &seanegan;
   &mlundblad;
+  &lance;
+  <revision>
+    <version>0.7</version>
+    <date>2015-10-20</date>
+    <initials>ls</initials>
+    <remark>
+      <ul>
+        <li>Clarified which attributes are needed to identify a service when requesting credentials.</li>
+        <li>Added 'action' attribute to indicate if a service is being added/removed/updated in a push update.</li>
+        <li>Added 'expires' attribute to indicate when provided credentials will expire.</li>
+        <li>Added 'restricted' attribute to indicate the need for fetching credentials for a service.</li>
+        <li>Bumped namespace version.</li>
+      </ul>
+    </remark>
+  </revision>
   <revision>
     <version>0.6</version>
     <date>2014-02-27</date>
@@ -111,7 +126,7 @@
 </section1>
 
 <section1 topic='Protocol' anchor='protocol'>
-  <p>In order to learn about external services known to an XMPP server or discovery service, a requesting entity (typically a client) sends an IQ-get containing an empty &lt;services/&gt; element qualified by the 'urn:xmpp:extdisco:1' namespace &NSNOTE;, typically to its own server but perhaps alternatively to a dedicated discovery service.</p>
+  <p>In order to learn about external services known to an XMPP server or discovery service, a requesting entity (typically a client) sends an IQ-get containing an empty &lt;services/&gt; element qualified by the 'urn:xmpp:extdisco:2' namespace &NSNOTE;, typically to its own server but perhaps alternatively to a dedicated discovery service.</p>
   <p>The responding entity (XMPP server or discovery service) SHOULD return the list of external services it is aware of, but MAY instead return an appropriate error, such as &unavailable; if the responding entity does not support this protocol or &forbidden; if the requesting entity does not have permission to receive the list of external services. Each service is encapsulated via a &lt;service/&gt; element.</p>
   <p>Note: The processes by which a responding entity discovers external services for "proxying" to XMPP entities are out of scope for this specification.</p>
   <p>The &lt;service/&gt; element MAY be empty or MAY include extended information about the service as described in the <link url='#extended'>Extended Information</link> section of this document.</p>
@@ -122,6 +137,16 @@
       <th>Definition</th>
       <th>Inclusion</th>
     </tr>
+    <tr>
+      <td>action</td>
+      <td>When sending a push update, the action value indicates if the service is being added or deleted from the set of known services (or simply being modified). The defined values are "add", "remove", and "modify", where "add" is the default.</td>
+      <td>OPTIONAL</td>
+    </tr>
+    <tr>
+      <td>expires</td>
+      <td>A timestamp indicating when the provided username and password credentials will expire. The format MUST adhere to the dateTime format specified in &xep0082; and MUST be expressed in UTC.</td>
+      <td>OPTIONAL</td>
+    </tr>
     <tr>
       <td>host</td>
       <td>Either a fully qualified domain name (FQDN) or an IP address (IPv4 or IPv6).</td>
@@ -142,6 +167,11 @@
       <td>The communications port to be used at the host.</td>
       <td>RECOMMENDED</td>
     </tr>
+    <tr>
+      <td>restricted</td>
+      <td>A boolean value indicating that username and password credentials are required and will need to be requested if not already provided (see <link url="#credentials">Requesting Credentials</link>).</td>
+      <td>OPTIONAL</td>
+    </tr>
     <tr>
       <td>transport</td>
       <td>The underlying transport protocol to be used when communicating with the service (typically either TCP or UDP).</td>
@@ -169,7 +199,7 @@
     id='ul2bc7y6'
     to='shakespeare.lit'
     type='get'>
-  <services xmlns='urn:xmpp:extdisco:1'/>
+  <services xmlns='urn:xmpp:extdisco:2'/>
 </iq>
     ]]></example>
     <example caption='XMPP Server Returns List'><![CDATA[
@@ -177,7 +207,7 @@
     id='ul2bc7y6'
     to='bard@shakespeare.lit/globe'
     type='result'>
-  <services xmlns='urn:xmpp:extdisco:1'>
+  <services xmlns='urn:xmpp:extdisco:2'>
     <service host='stun.shakespeare.lit'
              port='9998'
              transport='udp'
@@ -216,7 +246,7 @@
     id='yv2c19f7'
     to='shakespeare.lit'
     type='get'>
-  <services xmlns='urn:xmpp:extdisco:1' type='turn'/>
+  <services xmlns='urn:xmpp:extdisco:2' type='turn'/>
 </iq>
     ]]></example>
     <example caption='XMPP Server Returns List'><![CDATA[
@@ -224,7 +254,7 @@
     id='yv2c19f7'
     to='bard@shakespeare.lit/globe'
     type='result'>
-  <services xmlns='urn:xmpp:extdisco:1'
+  <services xmlns='urn:xmpp:extdisco:2'
             type='turn'>
     <service host='turn.shakespeare.lit'
              password='jj929jkj5sadjfj93v3n'
@@ -241,40 +271,46 @@
   </services>
 </iq>
     ]]></example>
-    <p>If a requesting entity requests services of a particular type, the responding service MAY as needed send an updated list of the relevant services by "pushing" the list to a requesting entity that has previously requested the list. However, it MUST NOT push updates to the requesting entity unless it has presence information about the requesting entity (e.g., because the requesting entity is connected to the XMPP server or because the requesting entity has shared presence with a remote discovery service). A push is an IQ set to the requesting entity containing a &lt;service/&gt; payload with updated data about services matching the requested type (e.g., new services or updated credentials)</p>
+    <p>If a requesting entity requests services of a particular type, the responding service MAY as needed send an updated list of the relevant services by "pushing" the list to a requesting entity that has previously requested the list. However, it MUST NOT push updates to the requesting entity unless it has presence information about the requesting entity (e.g., because the requesting entity is connected to the XMPP server or because the requesting entity has shared presence with a remote discovery service). A push is an IQ set to the requesting entity containing a &lt;services/&gt; payload with updated data about services matching the requested type (e.g., new services or updated credentials). Each &lt;service/&gt; element SHOULD contain an 'action' attribute indicating if the service is being added, deleted, or modified.</p>
     <example caption='Services Push'><![CDATA[
 <iq from='shakespeare.lit'
     id='lh3f1vc7'
     to='bard@shakespeare.lit/globe'
     type='set'>
-  <services xmlns='urn:xmpp:extdisco:1'
+  <services xmlns='urn:xmpp:extdisco:2'
             type='turn'>
-    <service host='stun.shakespeare.lit' 
+    <service action='add'
+             host='stun.shakespeare.lit' 
              port='9999' 
              transport='udp'
              type='turn'
              username='1nas9dlm3hzl89d0b9v' 
              password='gh9023ljjdk109iajqn'>
-    <service host='192.0.2.2' 
+    <service action='add'
+             host='192.0.2.2' 
              port='7778' 
              transport='udp'
              type='turn'
              username='bnsv120afg48snsdozp' 
              password='zxp023na98dsfahn1kk'/>
+    <service action='delete'
+             host='192.0.2.1'
+             port='8889'
+             type='turn'/>
   </services>
 </iq>
     ]]></example>
     <p>Upon receiving a push, the requesting entity would then send an IQ-result to the responding service in accordance with &xmppcore;.</p>
   </section2>
   <section2 topic='Requesting Credentials' anchor='credentials'>
-    <p>An entity might know about an external service via DNS or some other means, but still might need short-term credentials to use the service. The entity can request credentials by sending a special request to the server.</p>
+      <p>An entity might know about an external service via DNS or some other means, but still might need short-term credentials to use the service. The entity can request credentials by sending a special request to the server composed of a &lt;credentials/&gt; element qualified by the 'urn:xmpp:extdisco:2' namespace and contains a &lt;service/&gt; element which MUST include the 'host' and 'type' attributes to identify the desired service (the 'port' attribute MAY be provided if there are multiple services with the same host and type but different ports).</p>
     <example caption='Entity Requests Credentials at a Service'><![CDATA[
 <iq from='bard@shakespeare.lit/globe'
     id='xi2cax48'
     to='shakespeare.lit'
     type='get'>
-  <credentials xmlns='urn:xmpp:extdisco:1'>
+  <credentials xmlns='urn:xmpp:extdisco:2'>
-    <service host='turn.shakespeare.lit'/>
+    <service host='turn.shakespeare.lit' type='turn' />
   </credentials>
 </iq>
     ]]></example>
@@ -284,23 +320,25 @@
     id='xi2cax48'
     to='bard@shakespeare.lit/globe'
     type='get'>
-  <credentials xmlns='urn:xmpp:extdisco:1'>
+  <credentials xmlns='urn:xmpp:extdisco:2'>
     <service host='turn.shakespeare.lit'
+             type='turn'
              password='jj929jkj5sadjfj93v3n'
              username='nb78932lkjlskjfdb7g8'/>
   </credentials>
 </iq>
     ]]></example>
     <p>For TURN, the server might construct time-limited credentials as described in &turn-rest;.</p>
+    <p>There MAY be multiple &lt;service/&gt; elements in the result if more than one service matched the requested service identity (e.g., the same host provides service on multiple ports).</p>
     <p>If the server cannot obtain credentials at the service, it returns an appropriate stanza error, such as &notfound;, &remoteserver;, &timeout;, or &notauthorized;.</p>
   </section2>
 </section1>
 
 <section1 topic='Extended Information' anchor='extended'>
-  <p>If a server or service needs to include extended information, it SHOULD do so by including each bit of information as the XML character data of the &lt;value/&gt; child of a distinct &lt;field/&gt; element, with the entire set of fields contained within an &lt;x/&gt; element of type "result" qualified by the 'jabber:x:data' namespace (see &xep0004;); this &lt;x/&gt; element SHOULD be a child of the &lt;service/&gt; element qualified by the 'urn:xmpp:extdisco:1' namespace &NSNOTE;. Thus the IQ result SHOULD be of the following form:</p>
+  <p>If a server or service needs to include extended information, it SHOULD do so by including each bit of information as the XML character data of the &lt;value/&gt; child of a distinct &lt;field/&gt; element, with the entire set of fields contained within an &lt;x/&gt; element of type "result" qualified by the 'jabber:x:data' namespace (see &xep0004;); this &lt;x/&gt; element SHOULD be a child of the &lt;service/&gt; element qualified by the 'urn:xmpp:extdisco:2' namespace &NSNOTE;. Thus the IQ result SHOULD be of the following form:</p>
   <code><![CDATA[
 <iq type='result'>
-  <services xmlns='urn:xmpp:extdisco:1'>
+  <services xmlns='urn:xmpp:extdisco:2'>
     <service>
       <x type='result' xmlns='jabber:x:data'>
         <field var='[var-name]' label='[optional]'>
@@ -317,7 +355,7 @@
 </section1>
 
 <section1 topic='Determining Support' anchor='disco'>
-  <p>If an XMPP entity supports this protocol, it MUST report that fact by including a service discovery feature of "urn:xmpp:extdisco:1" &NSNOTE; in response to a &xep0030; information request:</p>
+  <p>If an XMPP entity supports this protocol, it MUST report that fact by including a service discovery feature of "urn:xmpp:extdisco:2" &NSNOTE; in response to a &xep0030; information request:</p>
   <example caption="Service Discovery Information Request"><![CDATA[
 <iq from='romeo@montague.lit/orchard'
     id='ix61z3m9'
@@ -332,7 +370,7 @@
     to='romeo@montague.lit/orchard'
     type='result'>
   <query xmlns='http://jabber.org/protocol/disco#info'>
-    <feature var='urn:xmpp:extdisco:1'/>
+    <feature var='urn:xmpp:extdisco:2'/>
   </query>
 </iq>
   ]]></example>
@@ -350,7 +388,7 @@
   <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
     <p>This specification defines the following XML namespace:</p>
     <ul>
-      <li>urn:xmpp:extdisco:1</li>
+      <li>urn:xmpp:extdisco:2</li>
     </ul>
     <p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
   </section2>
@@ -394,8 +432,8 @@
 
 <xs:schema
     xmlns:xs='http://www.w3.org/2001/XMLSchema'
-    targetNamespace='urn:xmpp:extdisco:1'
+    targetNamespace='urn:xmpp:extdisco:2'
-    xmlns='urn:xmpp:extdisco:1'
+    xmlns='urn:xmpp:extdisco:2'
     elementFormDefault='qualified'>
 
   <xs:import
@@ -414,7 +452,7 @@
   <xs:element name='credentials'>
     <xs:complexType>
       <xs:sequence>
-        <xs:element ref='service' minOccurs='0' maxOccurs='1'/>
+        <xs:element ref='service' minOccurs='0' maxOccurs='unbounded'/>
       </xs:sequence>
     </xs:complexType>
   </xs:element>
@@ -424,10 +462,21 @@
       <xs:sequence xmlns:xdata='jabber:x:data'>
         <xs:element ref='xdata:x' minOccurs='0'/>
       </xs:sequence>
+      <xs:attribute name='action' use='optional' default='add'>
+        <xs:simpleType>
+          <xs:restriction base='xs:NCName'>
+            <xs:enumeration value='add'/>
+            <xs:enumeration value='delete'/>
+            <xs:enumeration value='modify'/>
+          </xs:restriction>
+        </xs:simpleType>
+      </xs:attribute>
+      <xs:attribute name='expires' type='xs:dateTime' use='optional'/>
       <xs:attribute name='host' type='xs:string' use='required'/>
       <xs:attribute name='name' type='xs:string' use='optional'/>
       <xs:attribute name='password' type='xs:string' use='optional'/>
       <xs:attribute name='port' type='xs:string' use='required'/>
+      <xs:attribute name='restricted' type='xs:boolean' use='optional'/>
       <xs:attribute name='transport' type='xs:NCName' use='optional'/>
       <xs:attribute name='type' type='xs:NCName' use='required'/>
       <xs:attribute name='username' type='xs:string' use='optional'/>