forked from xsf/xeps
-
Notifications
You must be signed in to change notification settings - Fork 0
/
xep-0060.xml
7196 lines (7027 loc) · 368 KB
/
xep-0060.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
<!ENTITY ITEM "<item/>">
<!ENTITY ITEMS "<items/>">
<!ENTITY PUBSUB "<pubsub/>">
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Publish-Subscribe</title>
<abstract>This specification defines an XMPP protocol extension for generic publish-subscribe functionality. The protocol enables XMPP entities to create nodes (topics) at a pubsub service and publish information at those nodes; an event notification (with or without payload) is then broadcasted to all entities that have subscribed to the node. Pubsub therefore adheres to the classic Observer design pattern and can serve as the foundation for a wide variety of applications, including news feeds, content syndication, rich presence, geolocation, workflow systems, network management systems, and any other application that requires event notifications.</abstract>
&LEGALNOTICE;
<number>0060</number>
<status>Draft</status>
<type>Standards Track</type>
<sig>Standards</sig>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0004</spec>
<spec>XEP-0030</spec>
<spec>XEP-0068</spec>
<spec>XEP-0082</spec>
<spec>XEP-0131</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>pubsub</shortname>
<schemaloc>
<ns>pubsub</ns>
<url>http://xmpp.org/schemas/pubsub.xsd</url>
</schemaloc>
<schemaloc>
<ns>pubsub#errors</ns>
<url>http://xmpp.org/schemas/pubsub-errors.xsd</url>
</schemaloc>
<schemaloc>
<ns>pubsub#event</ns>
<url>http://xmpp.org/schemas/pubsub-event.xsd</url>
</schemaloc>
<schemaloc>
<ns>pubsub#owner</ns>
<url>http://xmpp.org/schemas/pubsub-owner.xsd</url>
</schemaloc>
<discuss>pubsub</discuss>
&pgmillard;
&stpeter;
&ralphm;
<revision>
<version>1.13.7</version>
<date>2017-08-24</date>
<initials>egp</initials>
<remark><p>Fix examples using invalid XEP-0082 dates.</p></remark>
</revision>
<revision>
<version>1.13.6</version>
<date>2017-06-22</date>
<initials>dg</initials>
<remark><p>Clarify behaviour of publish-options. Fields must be registered</p></remark>
</revision>
<revision>
<version>1.13.5</version>
<date>2016-12-21</date>
<initials>psa (XEP Editor: ssw)</initials>
<remark><p>Add missing options to schema.</p></remark>
</revision>
<revision>
<version>1.13.4</version>
<date>2016-12-02</date>
<initials>psa</initials>
<remark><p>Make Multiple Simultaneous Modifications examples consistent with text.</p></remark>
</revision>
<revision>
<version>1.13.3</version>
<date>2016-12-08</date>
<initials>ss (XEP Editor: ssw)</initials>
<remark><p>Include publisher with any item retrieval.</p></remark>
</revision>
<revision>
<version>1.13.2</version>
<date>2016-10-11</date>
<initials>ss (XEP Editor: ssw)</initials>
<remark><p>Be more consistent with reply.</p></remark>
</revision>
<revision>
<version>1.13.1</version>
<date>2016-07-21</date>
<initials>ss</initials>
<remark>
<ul>
<li>Fix wording, replace Jabber with XMPP where applicable.</li>
</ul>
</remark>
</revision>
<revision>
<version>1.13</version>
<date>2010-07-12</date>
<initials>psa</initials>
<remark>
<ul>
<li>Pending further discussion: added but then removed change to allow notifications via IQ stanzas; removed but then retained batch publishing; removed but then retained SubIDs in subscription approvals.</li>
<li>Corrected a large number of reported errata.</li>
<li>Removed delete-any feature.</li>
<li>Added missing delete-items feature.</li>
<li>Added special value of "presence" for the pubsub#expire option to support temporary subscriptions.</li>
<li>Removed replyto and replyroom config options.</li>
<li>Removed multiple node discovery since it depended on the deprecated Service Discovery Publishing feature.</li>
<li>Defined "room" value for itemreply config option.</li>
<li>Added optional 'publisher' attribute to <item/> element.</li>
<li>Added optional <redirect/> child to <delete/> element.</li>
<li>Based redirects on URIs for consistency with RFC 6120 gone and redirect errors.</li>
<li>Clarified meaning of filtered notifications (they are based on NodeIDs, not payload namespaces).</li>
<li>Added pubsub-on-a-jid service discovery feature for explicit discovery that an IM and presence account also functions as a virtual pubsub service.</li>
<li>Added purge_offline node configuration option for purging the node when the relevant publisher goes offline, for use in certain extended presence applications.</li>
<li>Added item_expire node configuration option for automatically removing items after a certain number of seconds.</li>
<li>Added notification_type node configuration option for defining which value of the <message/> type attribute shall be used for notifications.</li>
<li>Added retrieve-default-sub feature for retrieving default subscription configuration from a node (as you can retrieve default node configuration from the service).</li>
<li>Clarified suggested rules for payload definitions.</li>
<li>Mentioned that singleton pattern can be enforced by setting max_items to 1.</li>
<li>Removed the notion of batch publishing because it makes information coherence and atom handling excessively difficult.</li>
<li>Added error handling for too-many-subscriptions to help prevent a certain denial of service attack.</li>
<li>Added process for retrieving default subscription configuration options for leaf nodes, by omitting the 'node' attribute on the <default/> element (also added the <default/> element to the schema for the http://jabber.org/protocol/pubsub namespace, since it was missing).</li>
<li>Removed informational mapping of node meta-data to Dublin Core.</li>
</ul>
</remark>
</revision>
<revision>
<version>1.12</version>
<date>2008-09-03</date>
<initials>psa</initials>
<remark>
<ul>
<li>Specified that service should return ItemID on successful publish if no ItemID was provided in request.</li>
<li>Described the use of Result Set Management to return some but not all published items.</li>
<li>Defined pubsub#notify_sub config option so that owners can receive notifications of new subscriptions, unsubscribes, and other subscription changes.</li>
<li>Harmonized definition of +notify feature with implementation reality.</li>
<li>Moved text about collections to XEP-0248.</li>
</ul>
</remark>
</revision>
<revision>
<version>1.11</version>
<date>2008-03-05</date>
<initials>rm/psa</initials>
<remark><p>For collection nodes, changed name of node child element to associate and added disassociate child element to handle disassociation use case; corrected SHIM examples to conform to XEP-0131; modified lease expiry notification for consistency with other subscription-related notifications (i.e., not using SHIM header); renamed SHIM headers to Collection and SubID for consistency with HTTP and Email headers.</p></remark>
</revision>
<revision>
<version>1.10</version>
<date>2007-09-26</date>
<initials>psa</initials>
<remark>
<ul>
<li>In accordance with XMPP Council consensus, moved the auto-create, auto-subscribe, filtered-notifications, and last-published features from XEP-0163 to this specification</li>
<li>Clarified implications of auto-subscribe feature for handling of account owners, stable presence subscribers, and transient presence sharers</li>
<li>Updated filtered-notifications text and examples to track changes to XEP-0115</li>
<li>Added publish-options functionality</li>
<li>Added developer-friendly How It Works section</li>
<li>Defined member affiliation to properly implement whitelist feature</li>
<li>Split several long sections into smaller sub-sections.</li>
<li>Clarified that a pubsub service must generate an ItemID if the publisher does not provide one.</li>
<li>Specified recommended ItemID for singleton nodes.</li>
<li>Summarized triggers for sending notifications.</li>
</ul>
</remark>
</revision>
<revision>
<version>1.9</version>
<date>2006-09-13</date>
<initials>psa</initials>
<remark>
<ul>
<li>Replaced boolean send_item_subscribe node configuration option with more comprehensive send_last_published_item option per list discussion</li>
<li>Added deliver_notifications node configuration option to enable quiet nodes without notifications, if desired enabling pull-model item retrieval only.</li>
<li>Modified subscription and affiliation retrieval to return empty element if no results.</li>
</ul>
</remark>
</revision>
<revision>
<version>1.8</version>
<date>2006-06-27</date>
<initials>psa</initials>
<remark>
<ul>
<li>Defined five access models: open, presence, roster, authorize, and whitelist</li>
<li>Renamed pubsub#subscription_model feature to pubsub#access_model</li>
<li>Separated affiliations retrieval from subscriptions retrieval</li>
<li>Removed subscription information from affiliations management</li>
<li>Changed <entity/> element to <subscription/> element in response to subscription request</li>
<li>Clarified batch processing of item publication and item deletion</li>
<li>Added basic example to introduction</li>
<li>More fully specified node creation flows</li>
<li>More fully specified recommended behavior for caching last published item, including use of jabber:x:delay protocol</li>
<li>Specified that semantic meaning of NodeIDs must not be used to encapsulate hierarchy</li>
<li>More fully specified error conditions</li>
<li>Changed some feature-related conditions to <unsupported/> plus feature attribute</li>
<li>Changed some error conditions from <not-authorized/> to <forbidden/></li>
<li>Harmonized error conditions for unsubscribe if entity is not subscribed (unexpected-request rather than not-found)</li>
<li>Further defined error conditions related to item publication</li>
<li>Specified structure of <affiliations/>, <delete/>, <purge/>, and <subscriptions/> elements qualified by pubsub#owner namespace</li>
<li>Changed retrieval of default node configuration options to use <default/> element, not <configure/> element</li>
<li>Allowed caching of last published item</li>
<li>Added pubsub#deliver subscription option</li>
<li>Added meta-data fields for pubsub#owners and pubsub#contact</li>
<li>Changed element for retrieval of default node configuration options from <configure/> to <default/> to prevent ambiguity related to configuration of root collection node</li>
<li>Specified pubsub#node_type configuration field</li>
<li>Specified pubsub#collection SHIM header</li>
<li>Specified conformance with Resourceprep for nodes addressable as JIDs</li>
<li>Added pubsub#modify-affiliations feature</li>
<li>Added pubsub#digest_frequency field to subscribe_options FORM_TYPE</li>
<li>Added pubsub#roster_groups_allowed field to node_config FORM_TYPE</li>
<li>More clearly specified the requirements level (MUST, SHOULD, MAY) for each service discovery feature</li>
<li>Defined pubsub#include_body subscription option and the pubsub#body_xslt node configuration option to transform payload format into an XMPP message body, and clarified rules for inclusion of message bodies</li>
<li>Clarified nature of collections and association of a node to a collection</li>
<li>Specified that simultaneous subscriptions of type nodes and items are allowed to collection nodes</li>
<li>Added examples and further explanation of time-based and content-based subscriptions</li>
<li>Added Internationalization Considerations</li>
<li>Clarified terminology</li>
<li>Corrected and updated the schemas</li>
</ul>
</remark>
</revision>
<revision>
<version>1.7</version>
<date>2005-03-03</date>
<initials>psa/rm</initials>
<remark>
<ul>
<li>Reinstated pubsub#subscribe feature (deleted in error)</li>
<li>Added type attribute for the <create/> and <configure/> elements to differentiate between leaf nodes and collection nodes</li>
<li>In Section 8.1.7, changed affiliations retrieval support to SHOULD and added pubsub#retrieve-affiliations feature</li>
<li>In Section 8.1.10, removed two duplicate examples</li>
<li>In Section 8.1.12, clarified relationship between normal disco#info data and node meta-data (which uses a service discovery extension)</li>
<li>In Section 8.2.4, specified that node purgation MUST result in one event notification, not a notification per item</li>
<li>In Section 8.1.8, further specified handling of SubIDs</li>
<li>Clarified nature of the pubsub#type field</li>
<li>Mentioned that the forbidden error should be returned in response to certain operations requested by an outcast</li>
<li>Corrected datatype of max_items attribute from xs:string to xs:positiveInteger</li>
<li>Corrected <requesting-entity-not-subscribed/> error to <not-subscribed/> since the subscribed JID need not be that of the requesting entity</li>
<li>Added service discovery features for more optional use cases: retracting items, purging nodes, deleting nodes</li>
<li>Updated relevant registries</li>
</ul>
</remark>
</revision>
<revision>
<version>1.6</version>
<date>2004-07-13</date>
<initials>pgm/psa</initials>
<remark><p>Added service discovery features for pubsub#meta-data, and pubsub#retrieve-items. Added pubsub#subscription_depth configuration option. Specified pubsub-specific error condition elements qualified by pubsub#errors namespace.</p></remark>
</revision>
<revision>
<version>1.5</version>
<date>2004-07-07</date>
<initials>pgm/psa</initials>
<remark><p>Fixed typos. Added more details to the section on collections. Added paragraph to create node use case to allow the service to change the requested node-id to something which it creates. Added text about bouncing publish requests when the request does not match the event-type for that node. Added disco features for the jabber registrar. Changed affiliation verbiage to allow publishers to remove any item. Tweaked verbiage for create node, eliminated extra example. Fully defined XMPP Registrar submissions. Corrected schemas.</p></remark>
</revision>
<revision>
<version>1.4</version>
<date>2004-06-22</date>
<initials>pgm</initials>
<remark><p>Added subid syntax in a variety of places. Added more information about disco#info and disco#items support. Added more info about subscription options. Added collection information. Added implementation notes about subscription leases, and content-based pubsub services.</p></remark>
</revision>
<revision>
<version>1.3</version>
<date>2004-04-25</date>
<initials>psa</initials>
<remark><p>Editorial review; added one implementation note.</p></remark>
</revision>
<revision>
<version>1.2</version>
<date>2004-03-09</date>
<initials>psa</initials>
<remark><p>Added XMPP error handling.</p></remark>
</revision>
<revision>
<version>1.1</version>
<date>2004-01-14</date>
<initials>psa</initials>
<remark><p>Added XMPP Registrar Considerations subsection for Service Discovery category/type registration.</p></remark>
</revision>
<revision>
<version>1.0</version>
<date>2003-10-28</date>
<initials>psa</initials>
<remark><p>Per a vote of the Jabber Council, advanced status to Draft.</p></remark>
</revision>
<revision>
<version>0.16</version>
<date>2003-10-23</date>
<initials>pgm</initials>
<remark><p>Clarified JID addressing usage for nodes. Added specific MAY requirement for disco usage. Added sentence about implementations verifying that an entity has a subscription before getting the current items.</p></remark>
</revision>
<revision>
<version>0.15</version>
<date>2003-10-21</date>
<initials>pgm</initials>
<remark><p>Fixed invalid XML in examples for subscription deny/allow.</p></remark>
</revision>
<revision>
<version>0.14</version>
<date>2003-10-21</date>
<initials>pgm</initials>
<remark><p>Clarified restrictions on addressing nodes by JID. Added section on Approving and Denying Subscription Requests. Changed get-pending to use Ad-Hoc Commands. Changed semantics when sending in a form type='cancel' for pending subscriptions.</p></remark>
</revision>
<revision>
<version>0.13</version>
<date>2003-09-30</date>
<initials>pgm</initials>
<remark><p>Removed item as a possible child of subscribe and unsubscribe and pubsub in the schemas. Removed retract as a possible child of item in the pubsub#event schema. Added verbiage to requirements for addressing nodes either via JIDs or disco nodes.</p></remark>
</revision>
<revision>
<version>0.12</version>
<date>2003-08-13</date>
<initials>pgm/psa</initials>
<remark><p>Defined public vs. private nodes; described how changes to existing nodes might trigger meta-node events (e.g., configuration changes); changed <x/> to <event/> for #events namespace; added meta-data about meta-nodes; fully defined XMPP Registrar considerations.</p></remark>
</revision>
<revision>
<version>0.11</version>
<date>2003-06-25</date>
<initials>pgm</initials>
<remark><p>Removed subscription notifications since they have inherent issues. Removed empty implementation note sub-section.</p></remark>
</revision>
<revision>
<version>0.10</version>
<date>2003-06-11</date>
<initials>pgm</initials>
<remark><p>Fixed error example when returning 501 from an items-get request. Added note about receiving subscription requests when an entity is already subscribed. Fixed some entity elements in various subscription examples. Many were missing the node attribute. Added subscription change notification verbiage and example. Added verbiage and example of subscription state notification being sent to the requesting entity. Added disco#items information for getting a list of item identifiers for a single node. Added verbiage for returning the current entity element when a curent subscriber attempts to subscribe again.</p></remark>
</revision>
<revision>
<version>0.9</version>
<date>2003-04-30</date>
<initials>pgm</initials>
<remark><p>Include JID attributes in the entity elements when receiving your affiliations. Changed error code 406 (which was wrong) to 404, which is correct. Changed many 405 errors to 401, and modified the error table to make it more implementable (rules are more concrete). Added subscribe-options element for indicating subscriptions may be configured.</p></remark>
</revision>
<revision>
<version>0.8</version>
<date>2003-04-03</date>
<initials>pgm</initials>
<remark><p>Clarified the affiliations table and the semantics around subscribing and unsubscribing. Added protocol to get all of your affiliations in the service. Added protocol for services informing subscribers that configurable subscription options are available. Added protocol for obtaining existing node configuration settings and for concatenating configuration and node creation requests into a single stanza. Added meta-node implementation notes and specified the interaction with the XMPP Registrar and the meta NodeIDs. Added authorization notes to subscription options.</p></remark>
</revision>
<revision>
<version>0.7</version>
<date>2003-02-14</date>
<initials>pgm</initials>
<remark><p>Clarified requirements around what affiliations must be supported. Moved requirements about specifying entities which can subscribe and publish out of the MUSTs to MAYs. Changed SHOULD to MAY when talking about allowing entities to create nodes. Added ability to send configuration requests in the same stanza as a creation request.</p></remark>
</revision>
<revision>
<version>0.6</version>
<date>2003-02-06</date>
<initials>pgm</initials>
<remark><p>Added more details and an example about publishing without NodeID. Added more implementation notes about NodeIDs and persistent storage.</p></remark>
</revision>
<revision>
<version>0.5</version>
<date>2003-01-22</date>
<initials>pgm</initials>
<remark><p>Fixed header for delete item example. Added examples showing subscribers being notified of deleted items. Added examples for notification of node deletion, and configuration for node deletion. Added Subscriber option semantics and examples. Added examples for 402 and 407 errors on subscribe and create respectively. Added clarification about ItemID handling to impl notes.</p></remark>
</revision>
<revision>
<version>0.4</version>
<date>2003-01-21</date>
<initials>pgm</initials>
<remark><p>Clarified in-band and out-of-band configuration requirement. Added Delete Item privilege for all affiliations to the table. Added Delete item protocol for publishers and owners. Added 401 error case for subscribing to an illegal jid. Changed subscription request form. Added defaults to configuration form, and clarified role of the XMPP Registrar for the features show. Added text explaining the max_items attribute. Changed "last items" to "most recent items". Removed default configuration acceptance -- owners should just cancel. Added the notify_retract configuration option. Clarified error handling for affiliation modifications. </p></remark>
</revision>
<revision>
<version>0.3</version>
<date>2003-01-20</date>
<initials>pgm</initials>
<remark><p>Added subscription attribute for entities. Removed subscriber from the affiliations table. Clarified configuration details. Clarified JabberID usages. Added XMPP Registrar Considerations. Added link to XEP-0068 about the FORM_TYPE element in subscription request notifications. Fixed some typos in examples. Added unsupported configuration namespace to example. Added a default node configuration example. </p></remark>
</revision>
<revision>
<version>0.2</version>
<date>2003-01-02</date>
<initials>pgm</initials>
<remark><p>Added numerous implementation notes; added get-pending action with regard to subscriptions; added error table; changed purge and delete to use IQ type='set'.</p></remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-11-19</date>
<initials>pgm</initials>
<remark><p>Initial version.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<section2 topic='Overview' anchor='intro-overview'>
<p>The XMPP publish-subscribe extension defined in this document provides a framework for a wide variety of applications, including news feeds, content syndication, extended presence, geolocation, avatar management, shared bookmarks, auction and trading systems, workflow systems, network management systems, NNTP gateways, profile management, and any other application that requires event notifications.</p>
<p>This technology uses the classic "publish-subscribe" or "observer" design pattern: a person or application publishes information, and an event notification (with or without payload) is broadcasted to all authorized subscribers. In general, the relationship between the publisher and subscriber is mediated by a service that receives publication requests, broadcasts event notifications to subscribers, and enables privileged entities to manage lists of people or applications that are authorized to publish or subscribe. The focal point for publication and subscription is a "node" to which publishers send data and from which subscribers receive event notifications. Nodes can also maintain a history of events and provide other services that supplement the pure pubsub model.</p>
<p>This document defines a generic protocol that all pubsub applications can use. Compliant implementations are not required to implement all of the features defined here (see the <link url='#features'>Feature Summary</link>.) Other specifications may define "subsets" or "profiles" of publish-subscribe for use in specialized contexts, but such profiles are out of scope for this document.</p>
</section2>
<section2 topic='How It Works' anchor='intro-howitworks'>
<p>Although this specification is large because it defines many side use cases and possible error flows, the basic idea is simple:</p>
<ol>
<li>An entity publishes information to a node at a publish-subscribe service.</li>
<li>The pubsub service pushes an event notification to all entities that are authorized to learn about the published information.</li>
</ol>
<p>Perhaps the most popular application of pubsub-like functionality is content syndication, which has become familiar from the RSS and Atom (&rfc4287;) feeds associated with weblogs, news sites, and other frequently-updated information available on the Internet. Consider the example of a weblog published by <hamlet@denmark.lit>. When Hamlet writes a new weblog entry, his blogging software publishes the entry to a pubsub node hosted at <pubsub.shakespeare.lit>:</p>
<example caption='Publisher Publishes a New Weblog Entry'><![CDATA[
<iq type='set'
from='hamlet@denmark.lit/blogbot'
to='pubsub.shakespeare.lit'
id='pub1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='princely_musings'>
<item>
<entry xmlns='http://www.w3.org/2005/Atom'>
<title>Soliloquy</title>
<summary>
To be, or not to be: that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles,
And by opposing end them?
</summary>
<link rel='alternate' type='text/html'
href='http://denmark.lit/2003/12/13/atom03'/>
<id>tag:denmark.lit,2003:entry-32397</id>
<published>2003-12-13T18:30:02Z</published>
<updated>2003-12-13T18:30:02Z</updated>
</entry>
</item>
</publish>
</pubsub>
</iq>
]]></example>
<p>So that is the "pub" part of pubsub.</p>
<p>Now the pubsub service notifies all the subscribers about the new blog entry:</p>
<example caption='Service Notifies Subscribers'><![CDATA[
<message from='pubsub.shakespeare.lit' to='francisco@denmark.lit' id='foo'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='princely_musings'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
[ ... ENTRY ... ]
</item>
</items>
</event>
</message>
<message from='pubsub.shakespeare.lit' to='bernardo@denmark.lit' id='bar'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='princely_musings'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
[ ... ENTRY ... ]
</item>
</items>
</event>
</message>
<message from='pubsub.shakespeare.lit' to='horatio@denmark.lit' id='baz'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='princely_musings'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
[ ... ENTRY ... ]
</item>
</items>
</event>
</message>
<message from='pubsub.shakespeare.lit' to='bard@shakespeare.lit' id='fez'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='princely_musings'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
[ ... ENTRY ... ]
</item>
</items>
</event>
</message>
]]></example>
<p>Here is an even simpler example: a transient node that sends only event notifications without a payload:</p>
<example caption='A Transient Notification'><![CDATA[
<message from='pubsub.shakespeare.lit' to='francisco@denmark.lit'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='elsinore/doorbell'/>
</event>
</message>
]]></example>
<p>Naturally, the entities involved may need to complete other use cases in order to enable full pubsub functionality -- for example, the publisher may need to create the node (see <link url='#owner-create'>Create a Node</link>) and subscribers may need to sign up for event notifications (see <link url='#subscriber-subscribe'>Subscribe to a Node</link>). These use cases are fully described in the remainder of this document. (For information about which features are required and which are recommended or optional, consult the <link url='#features'>Feature Summary</link>.)</p>
</section2>
</section1>
<section1 topic='Glossary' anchor='glossary'>
<p>The following terms are used throughout this document to refer to elements, objects, or actions that occur in the context of a pubsub service. (Note: Some of these terms are specified in greater detail within the body of this document.)</p>
<dl>
<di><dt>Authorize Access Model</dt><dd>A node access model under which an entity can subscribe only through having a subscription request approved by a node owner (subscription requests are accepted but only provisionally) and only subscribers may retrieve items.</dd></di>
<di><dt>Address</dt><dd>(1) A JID as defined in &xmppcore;, or (2) the combination of a JID and a &xep0030; node.</dd></di>
<di><dt>Collection Node</dt><dd>A type of node that contains nodes and/or other collections but no published items. Collections make it possible to represent more sophisticated relationships among nodes. Collection nodes are defined in &xep0248;.</dd></di>
<di><dt>Entity</dt><dd>A JID-addressable XMPP entity (client, service, application, etc.).</dd></di>
<di><dt>Event</dt><dd>A change in the state of a node.</dd></di>
<di><dt>Instant Node</dt><dd>A node whose NodeID is automatically generated by a pubsub service.</dd></di>
<di><dt>Item</dt><dd>An XML fragment which is published to a node, thereby generating an event.</dd></di>
<di><dt>ItemID</dt><dd>A unique identifier for an item in the context of a specific node.</dd></di>
<di><dt>Leaf Node</dt><dd>A type of node that contains published items only. It is NOT a container for other nodes.</dd></di>
<di><dt>Node</dt><dd>A virtual location to which information can be published and from which event notifications and/or payloads can be received (in other pubsub systems, this may be labelled a "topic").</dd></di>
<di><dt>NodeID</dt><dd>The unique identifier for a node within the context of a pubsub service. The NodeID is either supplied by the node creator or generated by the pubsub service (if the node creator requests an Instant Node). The NodeID MAY have semantic meaning (e.g., in some systems or in pubsub profiles such as PEP the NodeID might be an XML namespace for the associated payload), but such meaning is OPTIONAL. If a document defines a given NodeID as unique within the realm of XMPP pubsub systems, it MUST specify the XML namespace of the associated payload.</dd></di>
<di><dt>Notification</dt><dd>A message sent to a subscriber informing them of an event.</dd></di>
<di><dt>Outcast</dt><dd>An entity that is disallowed from subscribing or publishing to a node.</dd></di>
<di><dt>Owner</dt><dd>The manager of a node, of which there may be more than one; often but not necessarily the node creator.</dd></di>
<di><dt>Open Access Model</dt><dd>A node access model under which any entity may subscribe and retrieve items without approval.</dd></di>
<di><dt>Payload</dt><dd>The XML data that is contained within the <item/> element of a publication request or an event notification. A given payload is defined by an XML namespace and associated schema. A document that defines a payload format SHOULD specify whether the payload can be used only for a NodeID whose value is the same as the XML namespace, or whether the payload can be used for any NodeID. Such a document also SHOULD specify whether it is suggested that node at which such payloads are published are best configured as <link url='#impl-singleton'>Singleton Nodes</link>.</dd></di>
<di><dt>Personal Eventing</dt><dd>A simplified subset of Publish-Subscribe for use in the context of instant messaging and presence applications, whereby each IM user's JID is a virtual pubsub service; for details, see &xep0163;.</dd></di>
<di><dt>Presence Access Model</dt><dd>A node access model under which any entity that is subscribed to the owner's presence with a subscription of type "from" or "both" (see &rfc3921;) may subscribe to the node and retrieve items from the node; this access model applies mainly to instant messaging systems.</dd></di>
<di><dt>Publisher</dt><dd>An entity that is allowed to publish items to a node and that is automatically subscribed to the node.</dd></di>
<di><dt>Publish-Only</dt><dd>An entity that is allowed to publish items to a node but that is not allowed to receive notifications. (This affiliation is useful in the context of nodes that do not have an open access model when automated entities need to generate notifications on behalf of the owner.)</dd></di>
<di><dt>Pubsub Service</dt><dd>An XMPP server or component that adheres to the protocol defined herein.</dd></di>
<di><dt>Roster Access Model</dt><dd>A node access model under which any entity that is subscribed to the owner's presence and in the specified roster group(s) may subscribe to the node and retrieve items from the node; this access model applies mainly to instant messaging systems.</dd></di>
<di><dt>Subscriber</dt><dd>An entity that is subscribed to a node.</dd></di>
<di><dt>Whitelist Access Model</dt><dd>A node access model under which an entity may subscribe and retrieve items only if explicitly allowed to do so by the node owner (subscription requests from unauthorized entities are rejected).</dd></di>
</dl>
</section1>
<!-- =================== REQS ======================== -->
<section1 topic='Requirements' anchor='reqs'>
<p>Requirements for a pubsub service can be driven by end-user needs as well as the needs of other components and services which can use the service. First, a pubsub service implemented using XMPP MUST provide the basic features that implement a pure publish-subscribe pattern:</p>
<!-- ================== MUSTS =================== -->
<ul>
<li>An entity MUST be able to publish events to a service such that all subscribers to a node receive notification of the event. See <link url='#publisher-publish'>Publish an Item to a Node</link>.</li>
<li>An entity MUST be able to subscribe to a node (or be informed that subscription is not allowed). See <link url='#subscriber-subscribe'>Subscribe to a Node</link>.</li>
<li>An entity MUST be allowed to be affiliated with a node. Allowable affiliations are member, none, outcast, owner, publish-only, and publisher. Implementations MUST support affiliations of none and owner, and MAY support affiliations of member, outcast, publisher, and publish-only. See <link url='#affiliations'>Affiliations</link>.</li>
<li>An entity MUST be allowed to query the pubsub service (or a specific node) to determine what optional features of this specification the service (or node) implements. This query MUST use the Service Discovery (disco#info) protocol. See <link url='#entity-info'>Discover Node Information</link>.</li>
</ul>
<!-- =================== MAYS and SHOULDS =================== -->
<p>Some of the possible uses of an XMPP-based pubsub service will require other features, but these features are OPTIONAL and therefore not mandatory for compliance with this specification. However, if these features are implemented, they MUST adhere to the protocol described herein in to be compliant. These features include:</p>
<ul>
<li>A service MAY cache the last item published to a node (even if the "persistent-items" option is set to false); if it does default "cache-last-item" to true, it SHOULD send the last published item (or notification thereof) to subscribed entities based on configuration of the "send_last_published_item" field.</li>
<li>A node owner SHOULD be able to specify who may subscribe to a node.</li>
<li>A node owner SHOULD be able to specify who may publish to a node.</li>
<li>A node MAY be configured to deliver the published payload inside the event notification.</li>
<li>A node MAY be configured to persist published items to some persistent storage mechanism.</li>
<li>A node MAY be configured to persist only a limited number of items.</li>
<li>A service MAY support collections as described in <cite>XEP-0248</cite>.</li>
<li>A service or node MAY support extended service discovery information (meta-data).</li>
</ul>
</section1>
<section1 topic='Preliminaries' anchor='preliminaries'>
<section2 topic='Affiliations' anchor='affiliations'>
<p>To manage permissions, the protocol defined herein uses a hierarchy of affiliations, similiar to those introduced in &xep0045;.</p>
<p>All affiliations MUST be based on a bare JID &BAREJID; instead of a full JID &FULLJID;.</p>
<p>Support for the "owner" and "none" affiliations is REQUIRED. Support for all other affiliations is RECOMMENDED. For each non-required affiliation supported by an implementation, it SHOULD return a service discovery feature of "name-affiliation" where "name" is the name of the affiliation, such as "member", "outcast", or "publisher" (see the <link url='#features'>Feature Summary</link>). Particular kinds of pubsub services MAY enforce additional requirements (e.g., requiring support for a given non-required affiliation or for all affiliations).</p>
<table caption='Affiliations and their Privileges'>
<tr>
<th>Affiliation</th>
<th>Subscribe</th>
<th>Retrieve Items</th>
<th>Publish Items</th>
<th>Delete Single Item</th>
<th>Purge Node</th>
<th>Configure Node</th>
<th>Delete Node</th>
</tr>
<tr>
<td>Owner</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
</tr>
<tr>
<td>Publisher</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes *</td>
<td>Yes *</td>
<td>No</td>
<td>No</td>
</tr>
<tr>
<td>Publish-Only</td>
<td>No</td>
<td>No</td>
<td>Yes</td>
<td>Yes *</td>
<td>No *</td>
<td>No</td>
<td>No</td>
</tr>
<tr>
<td>Member</td>
<td>Yes</td>
<td>Yes</td>
<td>No</td>
<td>No</td>
<td>No</td>
<td>No</td>
<td>No</td>
</tr>
<tr>
<td>None</td>
<td>Yes</td>
<td>No</td>
<td>No</td>
<td>No</td>
<td>No</td>
<td>No</td>
<td>No</td>
</tr>
<tr>
<td>Outcast</td>
<td>No</td>
<td>No</td>
<td>No</td>
<td>No</td>
<td>No</td>
<td>No</td>
<td>No</td>
</tr>
</table>
<p>* Note: A service MAY allow any publisher to delete / purge any item once it has been published to that node instead of allowing only the original publisher to remove it. This behavior is NOT RECOMMENDED for the publish-only affiliation, which SHOULD be allowed to delete only items that the publish-only entity has published.</p>
<p>The ways in which an entity changes its affiliation with a node are well-defined. Typically, action by an owner is required to make an affiliation state transition. Affiliation changes and their triggering actions are specified in the following table.</p>
<table caption='Affiliation State Chart'>
<tr>
<th> </th>
<th>Outcast</th>
<th>None</th>
<th>Member</th>
<th>Publisher</th>
<th>Owner</th>
</tr>
<tr>
<td>Outcast</td>
<td>--</td>
<td>Owner removes ban</td>
<td>Owner adds entity to member list</td>
<td>Owner adds entity to publisher list</td>
<td>Owner adds entity to owner list</td>
</tr>
<tr>
<td>None</td>
<td>Owner bans entity</td>
<td>--</td>
<td>Owner adds entity to member list</td>
<td>Owner adds entity to publisher list</td>
<td>Owner adds entity to owner list</td>
</tr>
<tr>
<td>Member</td>
<td>Owner bans entity</td>
<td>Owner removes entity from member list</td>
<td>--</td>
<td>Owner adds entity to publisher list</td>
<td>Owner adds entity to owner list</td>
</tr>
<tr>
<td>Publisher</td>
<td>Owner bans entity</td>
<td>Owner removes entity from publisher list</td>
<td>n/a</td>
<td>--</td>
<td>Owner adds entity to owner list</td>
</tr>
<tr>
<td>Owner</td>
<td>n/a</td>
<td>Owner resigns</td>
<td>n/a</td>
<td>n/a</td>
<td>--</td>
</tr>
</table>
</section2>
<section2 topic='Subscription States' anchor='substates'>
<p>Subscriptions to a node may exist in several states.</p>
<table caption='Subscription States'>
<tr>
<th>Subscription State</th>
<th>Description</th>
</tr>
<tr>
<td>None</td>
<td>The node MUST NOT send event notifications or payloads to the Entity.</td>
</tr>
<tr>
<td>Pending</td>
<td>An entity has requested to subscribe to a node and the request has not yet been approved by a node owner. The node MUST NOT send event notifications or payloads to the entity while it is in this state.</td>
</tr>
<tr>
<td>Unconfigured</td>
<td>An entity has subscribed but its subscription options have not yet been configured. The node MAY send event notifications or payloads to the entity while it is in this state. The service MAY timeout unconfigured subscriptions.</td>
</tr>
<tr>
<td>Subscribed</td>
<td>An entity is subscribed to a node. The node MUST send all event notifications (and, if configured, payloads) to the entity while it is in this state (subject to subscriber configuration and content filtering).</td>
</tr>
</table>
</section2>
<section2 topic='Event Types' anchor='events'>
<p>The requirements for the publish-subscribe protocol imply that there are two major dimensions along which we can measure events: persistent vs. transient, and pure event notification vs. inclusion of payload. An implementation SHOULD enable an owner to configure a node along both of these dimensions.</p>
<p>No matter whether a node is configured for persistent or transient events, a service MAY cache the last item published to the node, in which case it SHOULD send that item to subscribers based on configuration of the "send_last_published_item" option (see the <link url='#impl-caching'>Item Caching</link> section of this document); if the service supports the "http://jabber.org/protocol/pubsub#last-published" feature then the value of this option MUST default to "on_sub_and_presence" (though the service SHOULD allow the node owner to override the default).</p>
<p class='box'>Note: The "on_sub_and_presence" setting relates to the <em>subscriber's</em> presence, not the publisher's presence.</p>
<p>A pubsub service MUST validate publish requests against the configuration of the node along both of these dimensions (see the <link url='#publisher-publish'>Publish An Item to a Node</link> section of this document for the relevant error conditions).</p>
<p>The node configuration and desired event type determine whether an item must be provided by the publisher, whether the item includes a payload in the publish request or event notification, and whether an item ID is provided by the publisher or generated by the pubsub service. We can summarize the relevant rules as follows:</p>
<table caption='Items, Payloads, and Item IDs'>
<tr><th> </th><th>Notification-Only Node *</th><th>Payload-Included Node *</th></tr>
<tr>
<td><strong>Persistent Node **</strong></td>
<td>Publish request MUST include an &ITEM; element, which MAY be empty or MAY contain a payload; even if publish request contains a payload, pubsub service MUST NOT include the payload in event notifications; if publish request did not include item ID, pubsub service MUST generate item ID</td>
<td>Publish request MUST include an &ITEM; element, which SHOULD contain a payload; if publish request included a payload, event notifications MUST include the payload; if publish request did not include item ID, pubsub service MUST generate item ID</td>
</tr>
<tr>
<td><strong>Transient Node **</strong></td>
<td>Publish request MUST NOT include an &ITEM; element; payload is not included in publish request or event notifications, although event notifications MUST include an empty &ITEMS; element; item ID is neither provided in publish request nor generated by pubsub service</td>
<td>Publish request MUST include an &ITEM; element, which SHOULD contain a payload; if publish request included a payload, event notifications MUST include the payload; pubsub service MAY generate an item ID</td>
</tr>
</table>
<p>* Note: Whether the node is notification-only or includes payloads is determined by the "pubsub#deliver_payloads" configuration field.</p>
<p>** Note: Whether the node is persistent or transient is determined by the "pubsub#persist_items" configuration field.</p>
</section2>
<section2 topic='Node Types' anchor='nodetypes'>
<p>There are two types of nodes:</p>
<table caption='Node Types'>
<tr>
<th>Node Type</th>
<th>Description</th>
</tr>
<tr>
<td>Leaf</td>
<td>A node that contains published items only. It is NOT a container for other nodes. This is the most common node type.</td>
</tr>
<tr>
<td>Collection</td>
<td>A node that contains nodes and/or other collections but no published items. Collections make it possible to represent more sophisticated relationships among nodes. For details, refer to <cite>XEP-0248</cite>.</td>
</tr>
</table>
</section2>
<section2 topic='Node Access Models' anchor='accessmodels'>
<p>In order to make node creation simpler for clients, we define the following node access models (in order of openness):</p>
<table caption='Node Access Models'>
<tr>
<th>Access Model</th>
<th>Description</th>
</tr>
<tr>
<td>Open</td>
<td>Any entity may subscribe to the node (i.e., without the necessity for subscription approval) and any entity may retrieve items from the node (i.e., without being subscribed); this SHOULD be the default access model for generic pubsub services.</td>
</tr>
<tr>
<td>Presence</td>
<td>Any entity with a subscription of type "from" or "both" may subscribe to the node and retrieve items from the node; this access model applies mainly to instant messaging systems (see <cite>RFC 3921</cite>).</td>
</tr>
<tr>
<td>Roster</td>
<td>Any entity in the specified roster group(s) may subscribe to the node and retrieve items from the node; this access model applies mainly to instant messaging systems (see <cite>RFC 3921</cite>).</td>
</tr>
<tr>
<td>Authorize</td>
<td>The node owner must approve all subscription requests, and only subscribers may retrieve items from the node.</td>
</tr>
<tr>
<td>Whitelist</td>
<td>An entity may subscribe or retrieve items only if on a whitelist managed by the node owner. The node owner MUST automatically be on the whitelist. In order to add entities to the whitelist, the node owner SHOULD use the protocol specified in the <link url='#owner-affiliations'>Manage Affiliated Entities</link> section of this document, specifically by setting the affiliation to "member".</td>
</tr>
</table>
<p>A generic publish-subscribe implementation SHOULD support all of the defined access models, although specialized publish-subscribe implementations MAY support only a subset of the access models. Which access models are provided in a particular deployment is a matter of service provisioning (e.g., some restricted deployments may wish to lock down permissions so that only the "authorize" and "whitelist" access models are provided, or even only the "whitelist" access model).</p>
<p>A node creator or owner can override the default access model by specifying an appropriate value for the 'pubsub#access_model' configuration field (see the <link url='#owner-create'>Create a Node With Default Configuration</link> and <link url='#owner-configure'>Configure a Node</link> sections of this document).</p>
</section2>
<section2 topic='Addressing' anchor='addressing'>
<p>If a pubsub node is addressable, it MUST be addressable either (1) as a JID or (2) as the combination of a JID and a node. <note>These nodes are equivalent to those used in <cite>XEP-0030: Service Discovery</cite>.</note></p>
<section3 topic='JID' anchor='addressing-jid'>
<p>If a pubsub node is addressable as a JID, the NodeID MUST be the resource identifier, and MUST NOT be specified by the "user" portion (node identifier) of the JID (e.g. "domain.tld/NodeID" and "user@domain.tld/NodeID" are allowed; "NodeID@domain.tld" is not allowed <note>This rule does not apply to the root collection node, if any.</note>). JID addressing SHOULD be used when interacting with a pubsub node using a protocol that does not support the node attribute. For example, when a service makes it possible for entities to subscribe to nodes via presence, it would address nodes as JIDs. If a pubsub node is addressable as a JID, the pubsub service MUST ensure that the NodeID conforms to the Resourceprep profile of Stringprep as described in <cite>RFC 3920</cite>.</p>
<p>Consider the following example, in which the pubsub service is located at the hostname pubsub.shakespeare.lit.</p>
<example caption='Node addressed as domain.tld/NodeID'><![CDATA[
<iq to='pubsub.shakespeare.lit/news announcements'>
...
</iq>
]]></example>
<p>Now consider the following example, in which the pubsub service is located at pubsub@shakespeare.lit.</p>
<example caption='Node addressed as user@domain.tld/NodeID'><![CDATA[
<iq to='pubsub@shakespeare.lit/news announcements'>
...
</iq>
]]></example>
</section3>
<section3 topic='JID+NodeID' anchor='addressing-jidnode'>
<p>If a pubsub node is addressable as a JID plus node, the NodeID MUST be the value of both the Service Discovery 'node' attribute and the pubsub 'node' attribute; i.e., for discovery purposes, a pubsub node is equivalent to a Service Discovery node. If a pubsub node is addressable as a JID plus node, the pubsub service SHOULD ensure that the NodeID conforms to the Resourceprep profile of Stringprep as described in <cite>RFC 3920</cite>.</p>
<p>Consider the following example, in which the (virtual) pubsub service is located at hamlet@denmark.lit.</p>
<example caption='Node addressed as JID+NodeID'><![CDATA[
<iq to='hamlet@denmark.lit'>
<query node='princely_musings'/>
</iq>
]]></example>
</section3>
</section2>
</section1>
<section1 topic='Entity Use Cases' anchor='entity'>
<p>This section defines the use cases for and protocols to be used by any entity that wishes to interact with a publish-subscribe service, mainly focused on Service Discovery use cases.</p>
<section2 topic='Discover Features' anchor='entity-features'>
<p>A service MUST respond to service discovery information requests qualified by the 'http://jabber.org/protocol/disco#info' namespace. The "disco#info" result returned by a pubsub service MUST indicate the identity of the service and indicate which pubsub features are supported.</p>
<example caption='Entity Queries Pubsub Service Regarding Supported Features'><![CDATA[
<iq type='get'
from='francisco@denmark.lit/barracks'
to='pubsub.shakespeare.lit'
id='feature1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<example caption='Pubsub Service Returns Set of Supported Features'><![CDATA[
<iq type='result'
from='pubsub.shakespeare.lit'
to='francisco@denmark.lit/barracks'
id='feature1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<identity category='pubsub' type='service'/>
<feature var='http://jabber.org/protocol/pubsub'/>
</query>
</iq>
]]></example>
<p>The possible pubsub features are noted throughout this document and have been registered as described in the <link url='#registrar'>XMPP Registrar Considerations</link> section of this document. For information regarding which features are required, recommended, and optional, see the <link url='#features'>Feature Summary</link> section of this document.</p>
</section2>
<section2 topic='Discover Nodes' anchor='entity-nodes'>
<p>If a service implements a hierarchy of nodes (by means of <link url='#collections'>Collection Nodes</link>), it MUST also enable entities to discover the nodes in that hierarchy by means of the <strong>Service Discovery</strong> protocol, subject to the recommendations in <cite>XEP-0030</cite> regarding large result sets (for which &xep0055; or some other protocol SHOULD be used). The following examples show the use of service discovery in discovering the nodes available at a hierarchical pubsub service.</p>
<p>Note: Node hierarchies and collection nodes are OPTIONAL. For details, refer to the <link url='#impl-semantics'>NodeID Semantics</link> and <link url='#collections'>Collection Nodes</link> sections of this document.</p>
<p>In the first example, an entity sends a service discovery items ("disco#items") request to the root node (i.e., the service itself), which is a <link url='#collections'>Collection Node</link>:</p>
<example caption='Entity asks service for all first-level nodes'><![CDATA[
<iq type='get'
from='francisco@denmark.lit/barracks'
to='pubsub.shakespeare.lit'
id='nodes1'>
<query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>
]]></example>
<example caption='Service returns all first-level nodes'><![CDATA[
<iq type='result'
from='pubsub.shakespeare.lit'
to='francisco@denmark.lit/barracks'
id='nodes1'>
<query xmlns='http://jabber.org/protocol/disco#items'>
<item jid='pubsub.shakespeare.lit'
node='blogs'
name='Weblog updates'/>
<item jid='pubsub.shakespeare.lit'
node='news'
name='News and announcements'/>
</query>
</iq>
]]></example>
<p>In the second example, an entity sends a disco#items request to one of the first-level nodes, which is also a collection node:</p>
<example caption='Entity requests second-level nodes'><![CDATA[
<iq type='get'
from='francisco@denmark.lit/barracks'
to='pubsub.shakespeare.lit'
id='nodes2'>
<query xmlns='http://jabber.org/protocol/disco#items'
node='blogs'/>
</iq>
]]></example>
<example caption='Service returns second-level nodes'><![CDATA[
<iq type='result'
from='pubsub.shakespeare.lit'
to='francisco@denmark.lit/barracks'
id='nodes2'>
<query xmlns='http://jabber.org/protocol/disco#items'
node='blogs'>
<item jid='pubsub.shakespeare.lit'
node='princely_musings'/>
<item jid='pubsub.shakespeare.lit'
node='kingly_ravings'/>
<item jid='pubsub.shakespeare.lit'
node='starcrossed_stories'/>
<item jid='pubsub.shakespeare.lit'
node='moorish_meanderings'/>
</query>
</iq>
]]></example>
<p>If a node is a leaf node rather than a collection node and items have been published to the node, the service MAY return one &ITEM; element for each published item as described in the <link url='#entity-discoveritems'>Discover Items for a Node</link> section of this document, however such items MUST NOT include a 'node' attribute (since they are published items, not nodes).</p>
</section2>
<section2 topic='Discover Node Information' anchor='entity-info'>
<p>A pubsub service MUST allow entities to query individual nodes for the information associated with that node. The Service Discovery protocol MUST be used to discover this information. The "disco#info" result MUST include an identity with a category of "pubsub" and a type of either "leaf" or "collection".</p>
<p>Note: If a node has an identity type of "leaf", then it MUST NOT contain other nodes or collections (only items); if a node has an identity type of "collection", then it MUST NOT contain items (only other nodes or collections).</p>
<example caption='Entity queries collection node for information'><![CDATA[
<iq type='get'
from='francisco@denmark.lit/barracks'
to='pubsub.shakespeare.lit'
id='info2'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='blogs'/>
</iq>
]]></example>
<example caption='Service responds with identity of pubsub/collection'><![CDATA[
<iq type='result'
from='pubsub.shakespeare.lit'
to='francisco@denmark.lit/barracks'
id='meta1'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='blogs'>
<identity category='pubsub' type='collection'/>
</query>
</iq>
]]></example>
<example caption='Entity queries leaf node for information'><![CDATA[
<iq type='get'
from='francisco@denmark.lit/barracks'
to='pubsub.shakespeare.lit'
id='info1'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='princely_musings'/>
</iq>
]]></example>
<example caption='Service responds with identity of pubsub/leaf'><![CDATA[
<iq type='result'
from='pubsub.shakespeare.lit'
to='francisco@denmark.lit/barracks'
id='info1'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='princely_musings'>
...
<identity category='pubsub' type='leaf'/>
...
</query>
</iq>
]]></example>
</section2>
<section2 topic='Discover Node Metadata' anchor='entity-metadata'>
<p>The "disco#info" result MAY include detailed meta-data about the node, encapsulated in the &xep0004; format as described in &xep0128;, where the data form context is specified by including a FORM_TYPE of "http://jabber.org/protocol/pubsub#meta-data" in accordance with &xep0068;. If meta-data is provided, it SHOULD include values for all configured options as well as "automatic" information such as the node creation date, a list of publishers, and the like.</p>
<example caption='Entity queries a node for information'><![CDATA[
<iq type='get'
from='francisco@denmark.lit/barracks'
to='pubsub.shakespeare.lit'
id='meta1'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='princely_musings'/>
</iq>
]]></example>
<example caption='Service responds with information and meta-data'><![CDATA[
<iq type='result'
from='pubsub.shakespeare.lit'
to='francisco@denmark.lit/barracks'
id='meta1'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='princely_musings'>
<identity category='pubsub' type='leaf'/>
<feature var='http://jabber.org/protocol/pubsub'/>
<x xmlns='jabber:x:data' type='result'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/pubsub#meta-data</value>
</field>
<field var='pubsub#type' label='Payload type' type='text-single'>
<value>http://www.w3.org/2005/Atom</value>
</field>
<field var='pubsub#creator' label='Node creator' type='jid-single'>
<value>hamlet@denmark.lit</value>
</field>
<field var='pubsub#creation_date' label='Creation date' type='text-single'>
<value>2003-07-29T22:56:10Z</value>
</field>
<field var='pubsub#title' label='A short name for the node' type='text-single'>
<value>Princely Musings (Atom)</value>
</field>
<field var='pubsub#description' label='A description of the node' type='text-single'>
<value>Updates for Hamlet's Princely Musings weblog.</value>
</field>
<field var='pubsub#language' label='Default language' type='list-single'>
<value>en</value>
</field>
<field var='pubsub#contact' label='People to contact with questions' type='jid-multi'>
<value>bard@shakespeare.lit</value>
</field>
<field var='pubsub#owner' label='Node owners' type='jid-multi'>
<value>hamlet@denmark.lit</value>
</field>
<field var='pubsub#publisher' label='Publishers to this node' type='jid-multi'>
<value>hamlet@denmark.lit</value>
</field>
<field var='pubsub#num_subscribers' label='Number of subscribers to this node' type='text-single'>
<value>1066</value>
</field>
</x>
</query>
</iq>
]]></example>
<p>Note: Node meta-data can be set in many ways. Some of it is based on node configuration (e.g., the owner's JID) whereas some of it may be dynamic (e.g., the number of subscribers). Any static information to be provided in the node meta-data SHOULD be provided as fields in the node configuration form.</p>
<p>Note: The pubsub#language field SHOULD be list-single so that the pubsub service can present an appropriate list of languages and language codes.</p>
</section2>
<section2 topic='Discover Items for a Node' anchor='entity-discoveritems'>
<p>To discover the published items which exist on the service for a specific node, an entity MAY send a "disco#items" request to the node itself, and the service MAY return each item as a Service Discovery &ITEM; element. The 'name' attribute of each Service Discovery item MUST contain its ItemID and the item MUST NOT possess a 'node' attribute. This ItemID MAY then be used to retrieve the item using the protocol defined in the <link url='#subscriber-retrieve'>Retrieve Items from a Node</link> section of this document.</p>
<example caption='Entity requests all of the items for a node'><![CDATA[
<iq type='get'