Multiple Containment for LWS Containers

lws10-core/Operations/delete-resource.md

@@ -11,9 +11,11 @@ The delete resource operation is implemented using the HTTP DELETE method, as de
 The DELETE request targets the URI of the resource or container to remove. Clients MAY include an `If-Match` header with an ETag for concurrency checks, as described in the abstract operation.
 
 **Deletion and Containment:**
-When a resource is deleted, the server MUST atomically remove it from its parent container's `items` list. The parent container's `totalItems` count and ETag MUST be updated accordingly.
+When a resource is deleted, the server MUST atomically remove it from its parent container(s)' `items` list. Each affected parent container's `totalItems` count and ETag MUST be updated accordingly.
 
-For non-container resources, the server removes the resource content, its associated metadata (linkset), and the containment reference in the parent container.
+**Multiple containment:** If a resource belongs to multiple containers (when multiple containment is supported), a DELETE request permanently removes the resource and removes it from **all** parent containers. To remove a resource from a single container without deleting it, use the [Managing Containment](#manage-containment) operations instead.
+
+For non-container resources, the server removes the resource content, its associated metadata (linkset), and the containment references in all parent containers.
 
 For container resources, the server defaults to non-recursive deletion. If the container is not empty and recursion is not requested, the server MUST reject the request with 409 Conflict. If recursion is desired and supported, clients MUST use the `Depth: infinity` header, as defined in [[RFC4918]]. Servers that do not support recursion MUST reject such requests with 501 Not Implemented.
 

lws10-core/Operations/manage-containment.md

@@ -0,0 +1,86 @@
+#### Managing Containment
+
+When multiple containment is enabled, resources MAY belong to more than one container. This section defines the operations for adding existing resources to containers and removing resources from containers without deleting the resource itself.
+
+##### Adding a Resource to a Container
+
+To add an existing resource to a container, a client sends a PATCH request to the target container's linkset resource using the `application/linkset-patch+json` media type. The patch body specifies the containment link to add.
+
+The server MUST verify that:
+- The target container exists and the client is authorized to modify it.
+- The resource to be added exists.
+- Adding the resource would not create a cycle in the containment graph (no self-containment, no circular ancestry).
+
+On success, the server responds with 204 No Content. The container's `items` list and `totalItems` count are updated atomically.
+
+**Example (Add a resource to a container):**
+```
+PATCH /alice/shared/.meta HTTP/1.1
+Authorization: Bearer <token>
+Content-Type: application/linkset-patch+json
+If-Match: "meta-v3"
+
+{
+  "add": {
+    "linkset": [
+      {
+        "anchor": "/alice/shared/",
+        "item": [
+          { "href": "/alice/notes/shoppinglist.txt" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Response:
+```
+HTTP/1.1 204 No Content
+ETag: "meta-v4"
+```
+
+After this operation, `/alice/notes/shoppinglist.txt` appears in the `items` listing of both `/alice/notes/` and `/alice/shared/`. The resource now has two `rel="up"` links.
+
+##### Removing a Resource from a Container
+
+To remove a resource from a container without deleting the resource, a client sends a PATCH request to the container's linkset resource specifying the containment link to remove.
+
+The server MUST verify that:
+- The target container exists and the client is authorized to modify it.
+- The resource is currently a member of the target container.
+
+**Orphan handling:** If removing the resource from this container would leave it with no parent containers, the server MUST reject the request with 409 Conflict, unless the server supports orphan handling policies (e.g., automatic deletion of orphaned resources or moving them to a designated container). Servers that support automatic orphan handling MUST document their policy.
+
+On success, the server responds with 204 No Content.
+
+**Example (Remove a resource from a container):**
+```
+PATCH /alice/shared/.meta HTTP/1.1
+Authorization: Bearer <token>
+Content-Type: application/linkset-patch+json
+If-Match: "meta-v4"
+
+{
+  "remove": {
+    "linkset": [
+      {
+        "anchor": "/alice/shared/",
+        "item": [
+          { "href": "/alice/notes/shoppinglist.txt" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Response:
+```
+HTTP/1.1 204 No Content
+ETag: "meta-v5"
+```
+
+##### Concurrency Control
+
+All containment management operations MUST use optimistic concurrency control. Clients MUST include an `If-Match` header with the current ETag of the container's linkset resource. If the ETag does not match, the server MUST respond with 412 Precondition Failed. If the `If-Match` header is missing, the server MUST respond with 428 Precondition Required.

lws10-core/Operations/metadata.md

@@ -50,4 +50,6 @@ Metadata is managed by interacting with the resource's associated linkset URI. S
 
 - Restrictions: Servers MAY restrict modifications to specific links (like `up` or `items`) to maintain system integrity. If a server restricts `up` modifications, it MUST document this in its conformance statement.
 
+- Containment Management: When multiple containment is supported, containment relationships MAY be modified through PATCH operations on a container's linkset resource. See [Managing Containment](#manage-containment) for the specific protocol for adding and removing resources from containers.
+
 - Lifecycle: Metadata lifecycles are tied to the described resource; deleting a resource MUST result in the automatic removal of its associated linkset metadata.

lws10-core/index.html

@@ -247,6 +247,11 @@ <h2>Update resource</h2>
         <h2>Delete resource</h2>
 		<div data-include="Operations/delete-resource.md" data-include-format="markdown" data-include-replace="true"></div>
       </section>
+
+      <section id="manage-containment">
+        <h2>Managing Containment</h2>
+		<div data-include="Operations/manage-containment.md" data-include-format="markdown" data-include-replace="true"></div>
+      </section>
 	  <div data-include="Operations/rest-table.md" data-include-format="markdown" data-include-replace="true"></div>
     </section>
 

lws10-core/logicalresourceorganization.md

@@ -21,14 +21,24 @@ Link: </alice/notes/>; rel="up"
 
 A container's members are listed in its representation using the `items` property. The server manages this list; clients cannot modify it directly. Membership changes occur as a side effect of resource creation and deletion.
 
+### Multiple Containment
+
+Servers MAY support **multiple containment**, allowing a resource to belong to more than one container simultaneously. When multiple containment is enabled:
+
+- The containment graph forms a **directed acyclic graph (DAG)** instead of a tree.
+- A resource MAY have multiple `rel="up"` links, one for each parent container.
+- **No self-containment**: A container MUST NOT contain itself, directly or indirectly. The server MUST reject any operation that would create a cycle in the containment graph.
+
+Multiple containment enables sharing use cases where a single resource needs to appear in multiple organizational contexts without duplication. Containment links are managed through the [Managing Containment](#manage-containment) operations.
+
 ### Containment Integrity
 
 The server MUST maintain containment integrity at all times:
 
 - **Creation**: When a new resource is created in a container, the server MUST atomically add the resource to the container's `items` list.
 - **Deletion**: When a resource is deleted, the server MUST atomically remove it from its parent container's `items` list. Deleting a container requires the container to be empty, unless recursive deletion is explicitly requested.
 - **No orphans**: Every non-root resource MUST be reachable from the root container through the containment hierarchy.
-- **No cycles**: The containment hierarchy MUST form a tree. A container MUST NOT directly or indirectly contain itself.
+- **No cycles**: The containment graph MUST NOT contain cycles. A container MUST NOT directly or indirectly contain itself.
 
 ### Resource Identification