<remark>Accepted by vote of Council on 2021-01-20.</remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2021-01-18</date>
<initials>mp</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1topic='Introduction'anchor='intro'>
<p>The XMPP Network is a network of servers which each have their own administration policies, status reports, and other peculiarities. &xep0157; provides a consistent framework for reaching out to administrators and reporting abuse, incidents, or even giving feedback on the service, and the goal of this specification is to provide a similar framework for letting users (or other entities) know the server status in-band or out of band (in case of hard failures).</p>
<p>Centralized systems usually control both the infrastructure and client code, making it easy to hardcode information retrieval one way or the other.</p>
<p>The usual way of informing users of planned maintenance, partial or total outage was previously through "announce" modules that lets the admin broadcast server-wided messages. This approach has several drawbacks, as it will appear in most clients as a new discussion with the server JID, which can prove confusing. It also does not provide a way to reach the user when the XMPP server is offline.</p>
<p>This XEP provides:</p>
<ul>
<li>An informational way of exposing an external service endpoint containing machine-readable data using &xep0128;</li>
<li>A specification of the data this service should provide</li>
<li>A normative way of providing such information in-band, when the outage is not complete</li>
<li>A way to reference and archive such incidents, in a &xep0060; node</li>
<p>To make such discovery possible, we specify a &xep0128; mechanism that a server SHOULD return in response to service discovery information ("disco#info") requests sent to the bare domain of the server. This information MUST be scoped using a FORM_TYPE of "urn:xmpp:sos:0" (as already specified in <cite>XEP-0128</cite>) and data form fields registered for this purpose as defined in the <linkurl='#registrar'>XMPP Registrar Considerations</link> section of this document.</p>
<p>Links present inside the 'external-status-addresses' field SHOULD use HTTP/HTTPS protocol and the resources referenced MUST be available without authentication.</p>
<section2topic='External status format'anchor='json-schema'>
<p>TODO: do we want this to be XML or json? I have no real preference, in any case it should be preferably generated by a tool but easy to write by hand, as this needs to be usable in situations where time is the essence.</p>
<p>The format used for the external status is defined here, to allow a wide range
of compatibility across services and clients.</p>
<p>A client MUST ignore unknown extra fields present in the JSON file, to allow extensibility, and implementations MAY add other fields.</p>
<p>This extension has been thought for several different cases of service outages:</p>
<ul>
<li>A client failing to connect to a server is able to display an informative message to the user if the server is having issues.</li>
<li>A server experiencing difficulties is able to communicate it to the users, and clients can display the information prominently.</li>
<li>An external service can keep track of the various outages, either for a single server or a number of them, and present the information in a structured manner.</li>
</ul>
</section1>
<section1topic='Business Rules'anchor='rules'>
<p>A client implementing this extension MUST fetch the addresses of the external service and cache it
<p>Both the JSON and the XML format defined in this document allow for internationalization in the fields that are expected to be presented to the user as-is. The other fields are machine-readable and their various values SHOULD be translated in the implementing applications.</p>
<p>Client implementations MUST check the provenance of the pubsub notifications before displaying a notification, otherwise malicious entities could send fake outage events.</p>
<p>Server administrators MUST ensure the servers provided in 'external-status-addresses' are trusted, as malicious administrators of this server could use the referenced file
<p>&xep0068; defines a process for standardizing the fields used within Data Forms qualified by a particular namespace, and <cite>XEP-0128</cite> describes how to use field standardization in the context of service discovery. This section registers fields for server information scoped by the "urn:xmpp:sos:0" FORM_TYPE.</p>
