# Item delta

Item delta specifies how a given item - property, reference, container - is (to be) modified.

For an overview, please see the Deltas page.

## Item delta content

Just to summarize, an item delta consists of three sets of values:

1. values/yields to add (`add` set),

2. values/yields to delete (`delete` set),

3. values to replace (`replace` set).

Any given item delta is either of "add/delete" type or of "replace" type. It is not possible to specify `add` and/or `delete` and `replace` sets at the same time.

## Item delta application

Let us describe the application of an item delta on given prism item. There are two cases:

2. Application of "replace" deltas.

For the specification below, let:

• D = ( Da, Dd, Dr ) be the delta,

• Da, Dd, Dr being add, delete, and replace sets, respectively,

• I be the set of item values before D application,

• I' be the set of values after D application.

### Application of "replace" deltas

A "replace" delta is applied by clearing item values and replacing them with the values in delta `replace` set.

I' = Dr

The application is a two-step process:

1. Existing item values or yields matching the delta `delete` set are deleted.

2. Values or yields from `add` set are added.

Mathematical description is divided into two parts:

In fact, Dd does not contain values to be deleted but "deletion patterns" instead. Each value in I is compared with Dd and deleted if it matches any value there. This can be written as I -del/RVDI Dd.

Also, when adding values that have equivalents already present in I, we first remove those equivalents. (Effectively, it is a kind of "add-or-update" operation.) Let’s denote equivalents existing in I as Ir = I ∩RVDI Da.

So:

• I' = (I -del/RVDI Dd - Ir) ∪ Da

• i.e. I' = (I -del/RVDI Dd - (I ∩RVDI Da)) ∪ Da

Note that this is a slight difference introduced in midPoint 4.2. Before 4.2 we simply ignored values from Da that were present in I (under RVDI), i.e. the old behavior was:

I' = (I -del/RVDI Dd) ∪ (Da -RVDI I)

Finally, as a special rule: If we are adding a single value va to a single-valued item I = {vi}, and va is different from vi (vaRVDI vi) then we consider I to be ∅ i.e. we "clear" the item before applying the delta. Then:

I' = Da

Short description of Dd treatment:

1. If vd∈Dd has no metadata, simply remove vd from I. This is to ensure backward compatibility.

2. If vd∈Dd has metadata, find an equivalent value vi∼vd and remove these metadata from vi. (And remove vi if no metadata values remain.)

Short description of Da treatment:

1. If vaRVDI I, add va to I.

2. If vaRVDI I, find an equivalent value vi∼vd, and add yields from va to vi.

Exact description:

It is not feasible to provide a specification of delta application using set operations. Let us resort to a pseudocode instead.

Let:

• I be the item before application of specific va ∈ Da or vd ∈ Dd.

• I' be the result of the application.

• M(v) be the set of metadata values for prism value v.

• m1P m2 mean that metadata value m1 and m2 have equivalent provenance.

Then:

For each vd ∈ Dd:

1. If M(vd)=∅: The standard deletion is performed: I' = I -del/RVDI {vd}.

2. If M(vd)={ md1, …​, mdnd } (nd>0), we try to find vi∈I: viRVDI vd and then:

1. if vi does not exist, ignore vd (phantom delete)

2. if vi exists and M(vi)={ mi1, mi2, …​, mini }, then:

1. ∀mdx∈M(vd): delete all mikP mdx from M(vi),

2. if M(vi)=∅ after this operation, delete vi from I, i.e. I' = I - {vi}.

3. any other vjRVDI vd are ignored (we assume that they do not exist).

(See `Item.removeRespectingMetadata` method.)

For each va ∈ Da:

1. If M(va)=∅: The standard addition is performed: I' = (I - Ir) ∪ {va} where

1. Ir = { vi ∈ I | viRVDI va)

2. If M(va)={ ma1, …​, mana} (na>0), we try to find vi∈I: viRVDI va and then:

1. if vi does not exist, add va to I: i.e. I' = I ∪ {va} (standard addition),

2. if vi exists and M(vi)={ mi1, mi2, …​, mini }, then:

1. delete all conflicting-provenance metadata from vi, i.e. ∀max∈M(va) delete all mikP max from M(vi),

2. add all M(va) to M(vi).

3. any other vjRVDI va are ignored (we assume that they do not exist).

(See `Item.addRespectingMetadataAndCloning` method.)

1. A prism object, as it is an item as well, could be also described by item delta. But it makes little sense because objects are inherently single-valued items.
2. In theory, `add` and `delete` sets are sufficient to describe an item change. The `replace` set is a convenient way how to tell "clear everything and replace by me", without having to deal with existing values. This also means that it is a big difference between `null` replace set (meaning replace is not being applied) and empty replace set (meaning "delete everything").