xeps/xep-0469.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY namespace "urn:xmpp:bookmarks-pinning:0">
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>Bookmark Pinning</title>
  <abstract>This document defines an XMPP protocol extension to allow users to pin PEP Native Bookmarks.</abstract>
  &LEGALNOTICE;
  <number>0469</number>
  <status>Experimental</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XMPP IM</spec>
    <spec>XEP-0402</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>bookmarkspinning</shortname>
  &edhelas;
  <revision>
    <version>0.1.0</version>
    <date>2022-08-23</date>
    <initials>XEP Editor (jsc)</initials>
    <remark>Accepted by vote of Council on 2022-07-27.</remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2020-05-17</date>
    <initials>am</initials>
    <remark><p>Initial version.</p></remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>The &xep0402; defines a way to store Bookmarks using user PEP nodes and brings a support for extensions</p>
  <p>Some users might be interested to pin some important Bookmarks when managing them.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
  <p>This extensions allow clients to pin important bookmarks.</p>
</section1>
<section1 topic='Protocol' anchor='protocol'>
  <p>When saving a &xep0402; pinned item the client MUST add a new 'pinned' element within the 'extensions' element having the '&namespace;' namespace.</p>
  <example caption="Client adds a new bookmark"><![CDATA[
<iq from='juliet@capulet.lit/balcony' type='set' id='pip1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='urn:xmpp:bookmarks:1'>
      <item id='theplay@conference.shakespeare.lit'>
        <conference xmlns='urn:xmpp:bookmarks:1'
                    name='The Play&apos;s the Thing'
                    autojoin='true'>
          <nick>JC</nick>
          <extensions>
            <pinned xmlns=']]>&namespace;<![CDATA['/>
          </extensions>
        </conference>
      </item>
    </publish>
    ...
  </pubsub>
</iq>
]]></example>
</section1>
<section1 topic='Business Rules' anchor='rules'>
  <p> When handling a pinned item, a client SHOULD prioritize it and treat it as important. A client MAY display it using visual specificities (e.g., ordering, icon, color) to differenciate it from non-pinned items.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>See considerations in &xep0402;.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
    <p>This specification defines the following XML namespace:</p>
    <ul>
      <li>&namespace;</li>
    </ul>
    <p>The &REGISTRAR; includes this namespace in the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
  </section2>
  <section2 topic='Protocol Versioning' anchor='registrar-versioning'>
    &NSVER;
  </section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
  <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace=']]>&namespace;<![CDATA['
    xmlns=']]>&namespace;<![CDATA['
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0402: http://www.xmpp.org/extensions/xep-0402.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='pinned' type='empty'/>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
]]></code>
</section1>
</xep>