Lists as target state

What this is about

If you send a list field, for example employees on a company, the list describes the state afterwards: The list should have exactly these members. So the list is not an “add this”. It is a target state.

Before and after

flowchart LR
    subgraph vorher ["before: employees"]
      A1[Anna]
      B1[Ben]
      C1[Cem]
    end
    subgraph payload ["in the request"]
      A2["{ id: Anna }"]
      C2["{ id: Cem }"]
      D2["{ firstname: Dora }"]
    end
    subgraph nachher ["after: employees"]
      A3[Anna]
      C3[Cem]
      D3["Dora (new)"]
    end
    vorher --> payload --> nachher

Member	before	in the request	after
Anna	yes	with `id`	stays
Ben	yes	missing	gets removed: deleted (DELETE flag) or detached
Cem	yes	with `id`	stays
Dora	no	without `id`	is created (needs CREATE)

What happens to a removed member

Ben drops out of the list

1:n with DELETE1:n without DELETEn:m without DELETEn:m with DELETE

When: The relation employees has the DELETE flag, Ben is a dependent child.

1

CDMS
checks the delete role of the employee model
2

Hook
Ben's DELETE hooks run
3

CDMS→Database
deletes Ben, together with his own dependent children and files

Result: Ben no longer exists, read returns 404.

When: The relation items of an invoice has no DELETE flag, the items are independent.

1

CDMS→Database
sets the field of the other side on the item to empty, that is sponsorInvoice = null
2

CDMS
the item itself stays

Result: The item is detached: It still exists, but no longer belongs to any invoice. This does not need a role on the item model.

When: A role is removed from groups, the relation has no DELETE flag.

1

CDMS→Database
deletes the row in the join table

Result: Both objects stay, only their connection is gone.

When: A role is removed from the roles of a group, the relation has the DELETE flag.

1

CDMS→Database
deletes the row in the join table, just as without the flag

Result: The role stays, also for all other groups. DELETE has no effect on n:m, because the member can belong to other partners as well. See Many-to-many through a join table.

The list step by step

How CDMS reconciles a list

1

CDMS
collects the ids of all entries in the request
2

CDMS
removes every previous member whose id is not included from the list: delete (DELETE) or detach
3

CDMS
entries with id: link or update along, depending on flag and verb
4

CDMS
entries without id: create new, if the relation has CREATE
5

CDMS→Database
saves everything in one transaction

How entries with and without id are handled is described in The four cases in nested writing.

Empty list, missing list

What a list in the request does

Verb	List field in the request	Result
PUT	missing	all members removed
PUT	`null` or `[]`	all members removed
PATCH	missing	unchanged
PATCH	`null` or `[]`	all members removed
PUT, PATCH	partial list	exactly these members
Create	missing, `null` or `[]`	empty list

For every member, “removed” means: deleted with the DELETE flag, otherwise detached.

Order and duplicate entries

Order: A list in CDMS is a set, without positions. The order in the request is not saved. When you read, you set the order with order in the response of the list. Otherwise the order is not defined. See Filters in nested lists.
Duplicate entries: Two identical entries without id create two objects with Create and PUT, and one with PATCH. The same id twice with different values: the last entry wins. Send each member only once.

Pitfalls

What comes next

With and without id: The four cases in nested writing
Deleting and cascades: Dependent objects (cascades)
PUT and PATCH: PUT or PATCH? The null trap