diff --git a/inbox/pubsub-node-relationships.xml b/inbox/pubsub-node-relationships.xml new file mode 100644 index 000000000..15658a522 --- /dev/null +++ b/inbox/pubsub-node-relationships.xml @@ -0,0 +1,267 @@ + + +%ents; +]> + + +
+ Pubsub Node Relationships + This specification describes how to establish links between pubsub nodes, allowing for optional hierarchical organization. + &LEGALNOTICE; + xxxx + ProtoXEP + Standards Track + Standards + Council + + XMPP Core + XEP-0001 + XEP-0060 + + + + pubsub-relationships + + Jérôme + Poisson + goffi@goffi.org + goffi@jabber.fr + + + 0.0.1 + 2024-10-09 + jp +

First draft.

 + +
+ + +

There are many cases where pubsub nodes have a relationship: because a feature needs several nodes (e.g., &xep0346;) or because a node describes information for another one (or its items), like in &xep0470;.

+

Sometimes this relationship is hierarchical (e.g., &xep0277;, where comment nodes depend on blog items), or a tree-like hierarchy may be desirable (e.g., a file-sharing feature representing directories and files).

+

So far, to have this kind of relationship, two ways were used:

+ +

This specification proposes another solution, aiming to replace &xep0248; and is:

+ +

To make things simple, this specification only treats relationships between nodes. Other features (notably subscription to a hierarchy) will be managed in separate XEPs.

+ + + +

The design goals of this XEP are:

+ + + + + + + + + +

This specification defines two types of relationships:

+
    +
  • link: a "link" is a simple relationship between nodes. It indicates that multiple nodes are interconnected, either because a feature requires several nodes to function together (e.g., &xep0346;), or because one node extends another node or its items (e.g., &xep0470;).
    • +
  • parent: a "parent" is a hierarchical relationship where the referenced node is positioned higher in the hierarchy. It signifies that one or more nodes depend on the parent, such as when comment nodes rely on a microblog node (e.g., &xep0277;), or when a tree-like structure is required for organizing items (e.g., a file-sharing system that mimics directory/file structure).
    • +
+ + + +

To set a relationship, an XMPP client must first ensure that the pubsub service supports this specification (see Discovering Support below). Then the relationship is established by setting the relevant configuration field parameter to a node as explained in XEP-0060 §8.2 Configure a Node. The var "{urn:xmpp:pubsub-relationships:0}link" must be used for a "link" relationship, and the var "{urn:xmpp:pubsub-relationships:0}parent" must be used for a "parent" relationship.

+

When setting a relationship in the pubsub service, the service MUST ensure that the resulting graph does not contain any cycle. This means that it must be impossible to return to an initial node by following the relationships, whether they are labeled as "link" or "parent". By sequentially following these relationships, one must always end at a node without any outgoing "link" or "parent" relationships.

+

If setting a "link" or "parent" relationship would result in a cyclic graph, the service MUST reject the configuration with a <not-allowed/> error, specifying a pubsub-specific error condition of <invalid-option/>, and SHOULD include a human-readable text explaining the problem.

+

If when setting a "link" relationship, the linked node has a "parent" relationship, the pubsub service MUST set the same parent to the linking node. If the linking node has already a parent which is different from the "parent" of the linked node, the service MUST reject the configuration with a <not-allowed/> error, specifying a pubsub-specific error condition of <invalid-option/>, and SHOULD include a human-readable text explaining the problem.

+

If a "parent" relationship is set to a linked node, the "parent" of all linking node MUST be set to the same node by the service. A service MUST NOT accept a "parent" relationship set to a linking node: linking nodes' parent relationship are always automatically set by the service itself when the linked node's "parent" relationship is set. In other terms, "parent" field can't be set on a node if it has a "link" field. This is to be sure that linking nodes are always on the same level as the linked node. If a "parent" is set on a node with "link" field, the service MUST reject the configuration with a <not-allowed/> error, specifying a pubsub-specific error condition of <invalid-option/>, and SHOULD include a human-readable text explaining the problem.

+ + + +

The following rules apply to the "link" relationship:

+
    +
  • When a linked node is deleted, all linked nodes MUST be automatically deleted by the pubsub service.
    • +
  • Deleting a linking node does not affect the linked node or any other linking nodes.
    • +
  • The access model and publish model of nodes with a "link" relationship are independent.
    • +
  • When a parent of a linked node is modified, the parents of linking nodes MUST be automatically updated by the pubsub service, as explained in Setting a Relationship.
    • +
+ + + +

The following rules apply to the "parent" relationship:

+
    +
  • When a parent node is deleted, all child nodes MUST be automatically deleted by the pubsub service. This will recursively delete children of children and so on, resulting in the deletion of the entire branch of the parent node.
    • +
  • To access a node, an entity MUST have access to all parents. In other words, a pubsub service MUST NOT allow access to a node for an entity if that entity is not allowed by the access model of the node or any of its parents up to the root node.
    • +
  • To publish to a node, an entity MUST have publication rights for all parents. In other words, a pubsub service MUST NOT permit publishing to a node from an entity if that entity is not permitted by the publish model of the node or any of its parents up to the root node.
    • +
+ + + + + + +

Juliet XMPP client links an attachment node to a microblog node.

+ + + + + + urn:xmpp:microblog:0 + + + + +/iq>]]> + + + + + + + http://jabber.org/protocol/pubsub#node_config + + + urn:xmpp:microblog:0 + + [...] + + + +]]> + + + +

When a comment node for &xep0277; is created, Juliet’s XMPP client configures the parent relationship.

+ + + + + + urn:xmpp:microblog:0 + + + + +]]> + + + + + + + http://jabber.org/protocol/pubsub#node_config + + + urn:xmpp:microblog:0 + + [...] + + + + + ]]> + + + + +

By default, node discovery as explained at XEP-0060: Discover Nodes is unaffected by this specification. However, it is expected that a future specification will add an optional way to filter out or display linking nodes and/or child nodes, resulting in a much clearer listing of PubSub nodes. That also means that child nodes are not displayed when doing a disco request on a parent node; this is to avoid breaking existing implementations that would not expect to discover nodes on a non-collection node.

+

This specification is backward compatible: nodes remain accessible normally to unsupporting clients. The main difference for them will be the automatic deletion of linked and child nodes and the propagation rules for access models and publish models. Setting a relationship remains possible even for unsupporting clients, as it involves only a regular node configuration update.

+

A tree-like structure with "parent" relationships does not prevent node name conflicts: to be backward compatible, nodes are still available normally as they would in a flat structure. This means that names must always be unique within the pubsub service to avoid conflicts, even deep inside the "parent" hierarchy.

+

If a node is created without any relationship, a Pubsub service MAY automatically create relationships for well-known nodes. For instance, a "parent" relationship can be created to the corresponding microblog node if a &xep0277; comment node is created, or a "link" relationship can be created if a &xep0470; attachment node is detected. However, if a relationship (either "link" or "parent") is set when creating the node, the Pubsub service MUST NOT change it or add other relationships. This is useful for working with non-supporting clients while still maintaining a clean organization of nodes.

+

For "link" relationships, the first node to be created is the one which is linked. For example: in &xep0346;, the "template" node is the one which is linked, meaning that it's the "submitted" node which must link to it.

+

If one wants to delete a parent node without deleting all its descendants, the direct child must first be unparented; that is, their "parent" attribute must be set to another node name or removed entirely. Then, the parent node can be deleted.

+ + + + +

If a pubsub service supports the protocol specified in this XEP, it MUST advertise it by including the "urn:xmpp:pubsub-relationships:0" discovery feature in response to a &xep0030; information request.

+ + + +]]> + + + ... + + ... + +]]> + + + + +

The "parent" relationship enhances security by preventing accidental bad synchronization of permission changes. For example, if an &xep0277; blog node’s access model is changed from "open" to "whitelist", without this specification, all comment nodes must be manually updated one by one by the XMPP client, which is error prone. However, with this specification and a "parent" relationship in place, the permissions are automatically propagated according to the Parent Relationship Rules.

+ +

The automatic deletion of linked or child nodes might surprise end-users, especially when using non-supporting XMPP clients. If the hierarchy is not visible to the user, it may not be clear that other nodes will also be deleted automatically. Supporting clients should ensure that the automatic deletion is clear to end-user.

+ + + + +

This document does not require interaction with &IANA;.

+ + + +

TODO

+ + + +

Thanks to NLNet foundation/NGI Zero Core for funding the work on this specification.

+ + +