From 63a924c6372f7404325adf50f1640004f77a094e Mon Sep 17 00:00:00 2001
From: Hannes Schmidt <hannes@ucsc.edu>
Date: Mon, 10 May 2021 21:14:43 -0700
Subject: [PATCH] fixup! Specify update semantics (DataBiosphere/azul#2884)

Allow multiple versions of same entity or subgraph in non-delta staging areas.

https://github.com/HumanCellAtlas/dcp2/pull/6#discussion_r628353584
https://github.com/HumanCellAtlas/dcp2/pull/6#discussion_r625877760
---
 docs/dcp2_system_design.rst | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/docs/dcp2_system_design.rst b/docs/dcp2_system_design.rst
index a9ad2d7..30f19ce 100644
--- a/docs/dcp2_system_design.rst
+++ b/docs/dcp2_system_design.rst
@@ -720,9 +720,13 @@ descriptors, one for metadata files and one for subgraphs.
     DSS version of the metadata file, converting it to this restricted ISO
     syntax.
 
-   A staging area may only contain exactly one entity object with a given
-   ``entity_id``. This precludes more than one version of any entity or
-   assigning the same ``entity_id`` to entities of different types.
+   Entity objects that share a given ``entity_id`` in a staging area must all
+   have the same ``entity_type``. This precludes assigning the same
+   ``entity_id`` to entities of different types, but allows several versions
+   of one entity to coexist in a non-delta staging area. A delta staging area,
+   on the other hand, must contain at most one object with a given
+   ``entity_id``, and therefore only one version of that entity.
+   
 
    The ``.remove`` suffix is used to request the removal of an entity. It can
    only be used in staging areas that have the ``is_delta`` property set to
@@ -757,6 +761,10 @@ descriptors, one for metadata files and one for subgraphs.
    assigning the same ``entity_id`` to descriptors for file entities of
    different types.
 
+   Descriptor objects that share a given ``entity_id`` in a staging area must
+   all have the same ``entity_type``. A delta staging area may contain at most
+   one object with a given ``entity_id``.
+
 - The object name of a data file is::
 
     data/{file_name}
@@ -800,6 +808,12 @@ descriptors, one for metadata files and one for subgraphs.
    ``links_id``. This precludes more than one version of any subgraph or
    using the same ``links_id`` in subgraphs for different projects.
 
+   Subgraph objects that share a given ``links_id`` in a staging area must all
+   have the same ``project_id``. This precludes assigning the same
+   ``links_id`` to subgraphs for different projects, but allows several
+   versions of one subgraph to coexist in a non-delta staging area. A delta
+   staging area, on the other hand, must contain at most one object with a
+   given ``links_id``, and therefore only one version of that subgraph.
 
 .. [#]
    The staging area URI is guaranteed to end in a slash.